A API FRACTTAL pode usar o HTTP Hawk como protocolo de autenticação. Ela usa o MAC (Message Authentication Code), que é um mecanismo para fazer solicitações HTTP autenticadas por verificação criptográfica parcial.
Assim como o esquema de autenticação HTTP Basic, no esquema Hawk as credenciais do cliente incluem um identificador e uma chave. Entretanto, em contraste com o esquema HTTP Basic, a chave nunca é incluída na solicitação de autenticação, mas é usada para calcular o valor do campo MAC incluído na solicitação.
Os dados necessários para que o cliente se conecte à API FRACTTAL são a ID exclusiva e uma CHAVE SECRETA, que são atribuídas apenas uma vez à empresa.
Por razões de segurança, o ID exclusivo e a CHAVE SECRETA são conhecidos apenas pelo FRACTTAL SPA e pela empresa registrada.
A API FRACTTAL suporta apenas o algoritmo de hash sha256 para validação de HMAC e payload.
Cabeçalho da solicitação (Request Header)
O cabeçalho da solicitação de autorização consiste em campos no formato "key": "value", conforme mostrado na tabela a seguir:
| Campo | Requerido | Descrição |
|---|---|---|
id | Sim | ID exclusivo que identifica a empresa registrada. |
ts | Sim | Data com segundos no registro de data e hora no formato "Unix epoch". Essa data deve estar dentro de 60 segundos da data do servidor da API FRACTTAL. Se houver uma diferença muito grande, será retornado um erro. |
nonce | Sim | Uma string aleatória. Que deve ser exclusiva para cada solicitação feita. |
mac | Sim | O MAC deve ser codificado em base-64 a partir da string padronizada (consulte PADRONIZAÇÃO DE STRING). |
ext | Opcional | Dados específicos do aplicativo. |
hash | Opcional | Código base-64 da request payload.. |
app | Opcional | O ID do aplicativo. Obrigatório se a solicitação for gerada a partir de um aplicativo. |
dig | Opcional | O delegado do aplicativo. |
Como o mac é calculado?
O MAC da solicitação é calculado usando o algoritmo "hmac-sha-256" e a chave secreta na string normalizada. Esse resultado é codificado em base-64.
Exemplo do mac = "/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk="
Exemplo de cabeçalho de solicitação
Autorização: Hawk id="qUtGgNr7YTURDensMvGa1g",
mac="/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=",
ts=”1368116073″, nonce=”Wiok05gO”, app=”2HjRl8gWz5shfSXrwblRnw”
Cabeçalho de resposta
Toda resposta tem um cabeçalho Server-Authorization no cabeçalho. O cabeçalho tem o mesmo formato da solicitação, mas não tem tantos dados. O campo mac é sempre incluído e baseia-se nos dados que foram enviados na solicitação, os campos hash e ext são substituídos por valores específicos da resposta e a string do cabeçalho é diferente.
O hash é opcional e é um código base-64 da resposta request-payload.
Exemplo:
Autorização do servidor: Hawk
mac="YWojrFVgIjgd+RiPacnDwRcL8VtvcMEzahVfOpoLxoA=",
hash="yAF3A3y3uzLvNT2m/nVwsifn1+joCqu0uNWZS8RSv6Y=", hash="yAF3A3y3uzLvNT2m/nVwsifn1+joCqu0uNWZS8RSv6Y="
Normalização de strings
A cadeia de caracteres normalizada (ordenada) forma o valor do resumo HMAC do campo mac. Ela se baseia nos detalhes da solicitação e é composta de 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, um de hawk.1.header (cabeçalho de solicitação), hawk.1.response (cabeçalho de resposta). |
| ts | Data com segundos no registro de data e hora no formato "Unix epoch". |
| nonce | Uma cadeia de caracteres gerada aleatoriamente. |
| Method | O método HTTP da solicitação. Todas as letras devem estar em maiúsculas. |
| Request URI | Esse é o URI de solicitação HTTP. |
| Host | Host para onde a solicitação será enviada; a porta é omitida. |
| Port | A porta pela qual a conexão será feita. Normalmente, é a porta 443. |
| hash | Esse é o request-payload em base-64. Em branco se não existir. |
| ext | Dados específicos do aplicativo. Em branco se não existirem |
| app | O ID do aplicativo. Omitir se ele não existir |
| dlg | O delegado do aplicativo. Omitir, a menos que o campo app exista. Se o campo app existir, defina-o como em branco. |
Nota: Lembre-se de que deve haver uma quebra de linha entre cada campo.
Construção
Cabeçalho
ts
nonce
Solicitação de método
URI
Host
Porta
hash
ext
app
dlg
Exemplo com o campo app:
hawk.1.header
1353832234
j4h3g2
POST
/inventários/12345
app.fracttal.com
443
¶
¶
1234
¶
Validação da carga útil
A carga útil é o corpo da solicitação/resposta. Nossos clientes têm a possibilidade opcional de validar a carga útil. Isso não é obrigatório, mas é altamente recomendável fazer isso quando possível.
Quando a autenticação do cabeçalho é gerada, o cliente calcula um hash da carga útil usando o algoritmo que você especificou (sha-256). O hash é calculado com base nos seguintes valores concatenados (cada valor seguido pelo caractere de quebra de linha):
- Hawk.1.payload
- O tipo de conteúdo em letras minúsculas sem nenhum outro parâmetro (exemplo: application/json)
- A carga útil da solicitação antes de qualquer outra codificação de conteúdo.
Exemplo:
Carga útil: Obrigado por voar Hawk
Tipo de conteúdo: text/plain.
A construção da carga útil é a seguinte:
hawk.1.payload
text/plain
Obrigado por voar com o Hawk
O valor de hash resultante (sha-256) é:
Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=
Portanto, a solicitação do cliente deve ter a seguinte aparência:
hawk.1.header
1353832234
j4h3g2
POST
/inventários/1234
app.fracttal.com
443
Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=
¶
some-app-ext-data
TS (Timestamp) fora do intervalo
Quando o ts do cliente estiver fora do intervalo de ±60 segundos do servidor, o servidor retornará o código, com o cabeçalho WWW-Authenticate contendo a data e a hora do servidor em registro de data e hora. O cálculo desse campo deve ser ajustado de acordo com a data e a hora da resposta.
Incluído na resposta está o campo tsm, que é um HMAC de um cabeçalho e data, seguido por uma nova linha para evitar ataques mal-intencionados.
Exemplo:
WWW-wAuthenticate: Hak ts="1365741469″,
tsm="b4Qqqhz8OUBq21saghHLV1ktwlXE72T1xtTEZkSlWizA=",
error="Stale timestamp" (registro de data e hora desatualizado)
Nota: Para saber mais sobre o esquema de autenticação Hawk, visite a página a seguir. Documentação oficial do Hawk