Autenticação

A autenticação para emissão do certificado utilizará o protocolo HMAC para envio de mensagens JSON. Objetivo: permitir a comunicação entre um Cliente e o Servidor com segurança.

Nonce

O número nonce deve ser composto por uma parte pseudoaleatória com 4 (quatro) números concatenada com o timestamp (Unix Timestamp sem microssegundos).

O Servidor sempre irá verificar se o nonce1 enviado pelo Cliente na requisição está dentro de uma margem de tolerância em relação ao relógio do Servidor. Se o timestamp do nonce1 estiver fora dessa margem o Servidor irá recusá-lo e enviar uma mensagem de erro NONCE fora do intervalo esperado.

O Cliente também deve verificar se o nonce2 enviado pelo Servidor na resposta da requisição está dentro da margem de tolerância. No nonce1 27031597863865, por exemplo, 2703 é a parte pseudoaleatória e 1597863865 é o UNIX timestamp (19 de Agosto de 2020 19:04:25 UTC/GMT).

HMAC

O protocolo HMAC prevê comunicação sem sessão para mensagens imunes a ataques de replay (valida-dados-emissao e recuperar-certificado) e comunicação com sessão para transações sensíveis a ataque de replay (emitir-certificado).

O Servidor define o algoritmo de hash H() a ser utilizado para cálculo do HMAC. Recomendamos SHA256 ou superior.

Cliente e Servidor devem utilizar a mesma chave keypara cálculo do HMAC. Essa chave deve ter tamanho e entropia suficiente para desestimular ataques de força bruta e de dicionário.

A key utilizada será a senha de emissão do Certificado Digital. Senha na qual o cliente cadastrou no momento da solicitação do certificado.

O hmac de cada mensagem é calculado da seguinte forma:

$$hmac = H ( H ( hkey ) || m )$$

H() : algoritmo de hash hkey : chave utilizada para o cálculo || : concatenação de strings m : mensagem

A chave hkey é definida de três formas diferentes:

$$hkey = nonce1 ║ key$$

nonce1 : Nonce enviado pelo Cliente key : Senha de emissão do Certificado

Essa primeira forma é utilizada para mensagens sem sessão e para a mensagem de abertura de sessão enviada pelo Cliente.

$$hkey=nonce1║key║nonce2$$

nonce1 : Nonce enviado pelo Cliente key : Senha de emissão do Certificado nonce2 : Nonce enviado pelo Servidor

Essa segunda forma é utilizada somente para a mensagem de confirmação de abertura de sessão enviada pelo Servidor.

$$hkey=nonce1║key║c║nonce2$$

nonce1 : Nonce enviado pelo Cliente key : Senha de emissão do Certificado c : Contador de mensagem nonce2 : Nonce enviado pelo Servidor

Essa terceira forma é utilizada em todas as mensagens após a abertura de sessão e considera a numeração das mensagens. O Servidor ao responder à mensagem 1, terá c também definido como 1.

Mensagens em JSON

Por questões de compatibilidade, a mensagem JSON deve obedecer aos seguintes critérios:

• Não deve conter espaços desnecessários (por exemplo, espaços e quebras de linha entre os elementos do JSON).

• Os nomes/descritores dos elementos devem estar entre aspas duplas.

• Os valores dos elementos também devem estar entre aspas duplas.

• Apenas valores numéricos (inteiros ou de ponto flutuante) podem estar sem as aspas duplas.

HMAC sem sessão

Para serviços sem sessão, o fluxo será:

1. Requisição: O Cliente envia por POST para a URL do serviço os seguintes campos:

   1. mensagem: mensagem JSON para o Servidor

   2. hmac: HMAC calculado pelo Cliente

   3. nonce1: Nonce gerado pelo Cliente

2. Resposta: O Servidor gera como resposta um JSON com dois elementos:

   1. mensagem: resposta JSON para o Cliente

   2. hmac : HMAC calculado pelo Servidor

Se ocorrer algum erro, a mensagem gerada pelo servidor será um JSON com apenas o elemento erro, que por sua vez terá dois elementos: codigo (código do erro) e mensagem (descrição do erro). O hmac será calculado pelo servidor sobre essa mensagem de erro.

Exemplo de comunicação sem sessão

Requisição do Cliente

Form data - POST

mensagem : {"texto":"Teste de mensagem 123456789"}
hmac     : 008122741367c0d96e150b67823f9e346b57dfb5f82ad5618cbc40fe0213f742
nonce1   : 45651597936518

Cálculo do HMAC em PHP

Exemplo de resposta do Servidor

Resposta válida

{
    "mensagem": {
        "texto": "Teste de mensagem 123456789",
        "inicio": "N\u00c3O"
    },
    "hmac": "cfb3101004e164e99b4bfa033891c1b31c03269717fe620e1618dc3b53e4f4ba"
}

Resposta de erro

{
    "mensagem": {
        "erro": {
            "codigo": 5,
            "mensagem": "Requisi\u00e7\u00e3o inv\u00e1lida (HMAC)"
        }
    },
    "hmac": "85e5432bafbac68987161a61c972cf9989ab40d7a68bd18392dde128c92ce22a"
}

HMAC com sessão

O Cliente deve iniciar a sessão através de uma comunicação hmac sem sessão. O Servidor enviará na confirmação de abertura de sessão um ou mais cookies de identificação da sessão. O Cliente deve enviar esses cookies em todas as requisições da sessão.

Na abertura da sessão o Cliente enviará o nonce1, e o Servidor enviará na confirmação de abertura de sessão o nonce2. Cliente e o Servidor usarão esses mesmos nonce1 e nonce2 para calcular o hmac de todas mensagens posteriores à abertura da sessão.

Na comunicação hmac com sessão, as mensagens são numeradas. A primeira mensagem enviada pelo Cliente ao Servidor após a abertura da sessão é a mensagem número 1. Cliente e Servidor devem manter a contagem das mensagens, mas sem transmitir o número da mensagem.

O fluxo de mensagens com sessão será:

1. Requisição de abertura de sessão: O Cliente envia por POST para a URL do serviço os seguintes campos:

   1. mensagem: {"session":"Sinerg_HMAC_Session_Request"}

   2. hmac: HMAC calculado pelo Cliente

   3. nonce1: Nonce gerado pelo Cliente

2. Resposta de abertura de sessão: O Servidor gera como resposta um JSON com três elementos:

   1. mensagem: {"session":"Sinerg_HMAC_Session_Response"}

   2. hmac: HMAC calculado pelo Servidor

   3. nonce2: Nonce gerado pelo Servidor

3. Requisição #1: O Cliente envia por POST para a URL do serviço :

   1. mensagem: mensagem JSON para o Servidor

   2. hmac: HMAC calculado pelo Cliente

   3. nonce1: Nonce gerado pelo Cliente

4. Resposta #1: O Servidor gera como resposta um JSON com dois elementos:

   1. mensagem: resposta JSON para o cliente

   2. hmac : HMAC calculado pelo Servidor

5. Requisição #n: O Cliente envia por POST para a URL do serviço :

   1. mensagem: mensagem JSON para o Servidor

   2. hmac: HMAC calculado pelo Cliente

   3. nonce1: Nonce gerado pelo Cliente

6. Resposta #n: O Servidor gera como resposta um JSON com dois elementos:

   1. mensagem: resposta JSON para o Cliente

   2. hmac : HMAC calculado pelo Servidor

Após a abertura de sessão o Servidor enviará os cookies de identificação de sessão, eles devem ser enviados a cada requisição.

Exemplo de comunicação com sessão

Requisição do Cliente

Form Data - POST

mensagem : {"session":"_Sinerg_HMAC_Session_Request_"
hmac     : d9df84b0b31719e9408847a27d73329689f54b2b5ee417e5a699bbd966975a95
nonce1   : 67511597937906

Cálculo do HMAC em PHP

Servidor confirma abertura de sessão

{
    "mensagem": {
        "session": "_Sinerg_HMAC_Session_Response_"
    },
    "nonce2": "33011597938058",
    "hmac": "0df00f5a4a1208d87ace3bb62c09baade0cbc913c91d369c7c9276a7a0242a11"
}

Cookie enviado pelo Servidor: PHPSESSID=4ca595a215510028bbf48dd9ad29f24e

Cliente envia requisição #1

Form Data - POST

mensagem : {"texto":"Mensagem #1 1427197736998"}
hmac     : 5f5cbf39d154a67560767c9abd6fcc3356170f1ad64c69b10ebb10657e410e62
nonce1   : 63171597939071

Cálculo do HMAC em PHP

Cookie enviado pelo Cliente: PHPSESSID=4ca595a215510028bbf48dd9ad29f24e

Servidor responde à requisição #1

{
    "mensagem": {
        "texto": "Mensagem #1 1427197736998",
        "datetime": "Tue, 24 Mar 2015 08:48:57 -0300"
    },
    "hmac": "e694ff5b3ddb323cbff75e46ae838de23f56a2595bed1f8acf1994b1f2e14bf0"
}

Serviços auxiliares