Autenticação com assinatura

Para garantir maior comodidade e segurança aos seus clientes, o e-SiTef oferece, além da autenticação através da chamada POST à URL cadastrada (saiba mais), a opção de assinatura de mensagens, em que conteúdo e remetente passam a ter garantias de integridade e autenticidade, respectivamente. Dessa forma, a loja recebe as informações da transação recém-criada diretamente na resposta de sua chamada REST e não mais através do POST de autenticidade.

O que você precisará

Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte);
A criação de uma chave pública e o gerenciamento da sua respectiva chave privada;
Cadastro da chave pública no e-SiTef (feito através da nossa equipe de suporte).

Criando as chaves pública e privada

Exemplos de como criar as chaves privada e pública:

No Linux (utilizando o terminal):

# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

# criando uma chave pública a partir da chave privada criada:
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

No Windows:

Utilizar ssh-keygen no prompt de comando

# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

Utilizar uma versão do openssl para windows, executar como administrador e executar o seguinte comando:

# criando uma chave pública a partir da chave privada criada:
rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Atenção:

Esse arquivo de chave pública jwtRS256.key.pub é o único arquivo que você deverá enviar pra nossa equipe de suporte. Sempre mantenha seguros a sua chave privada e a sua senha, caso tenha cadastrado uma.

Algoritmo de assinatura

O algoritmo suportado pela aplicação é o RS256 em conjunto com o padrão JWT (RFC 7519).

Ao utilizar este padrão, uma assinatura é composta por três partes: cabeçalho, dados (payload) e a verificação de assinatura. A cada uma dessas partes, é aplicada uma codificação Base64.

Primeira parte (cabeçalho)

O cabeçalho deve conter o seguinte conteúdo fixo:

{
  "alg": "RS256",
  "typ": "JWT"
}

Cabeçalho Base64:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Segunda parte (payload)

A parte de dados (payload) varia de acordo com a operação a ser assinada. Exemplo:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn" : "92837429837",
  "timestamp": "1605034925174"
}

Payload Base64:

eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

Composição do payload

Dependendo do serviço chamado, os campos do payload serão diferentes. Abaixo estão descritos os campos necessários para cada serviço.

Serviços de criação e listagem de lojas

Parâmetro	Descrição	Formato	Obrigatório
`merchant_id`	Código da loja no e-SiTef.	= 15 AN	SIM
`merchant_key`	Chave de autenticação da loja no e-SiTef.	< 80 AN	SIM
`timestamp`	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

Serviços de edição e consulta de loja

Parâmetro	Descrição	Formato	Obrigatório
`merchant_id`	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM
`merchant_key`	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
`timestamp`	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM
`registered_merchant_id`	Código da loja criada ou a ser criada no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "registered_merchant_id": "YYYYYYY",
  "timestamp": "1605034925174"
}

Serviços de criação de transação

Parâmetro	Descrição	Formato	Obrigatório
`merchant_id`	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM
`merchant_key`	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
`order_id`	Código do pedido definido pelo lojista.	< 40 AN	SIM
`merchant_usn`	Número sequencial único para cada pedido, criado pela loja.	< 12 N	SIM
`timestamp`	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

Exemplo:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn" : "92837429837",
  "timestamp": "1605034925174"
}

Demais serviços

Parâmetro	Descrição	Formato	Obrigatório
`nit`	Identificador da transação no e-SiTef.	= 64 AN	SIM
`merchant_id`	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM
`merchant_key`	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
`timestamp`	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

Exemplo:

{
  "nit":"asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678",
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

Terceira parte (verificação)

A terceira e última parte é o resultado da criptografia RSA das duas partes anteriores codificadas separadamente em Base64 e concatenadas por um ponto (".").

Duas partes anteriores codificadas seperadamente em Base64 e concatenadas por um ponto ("."), onde o primeiro segmento do texto - anterior ao ponto - corresponde ao cabeçalho e o segundo corresponde ao payload:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

Por fim, uma criptografia RSA, usando a chave privada loja, deve ser feita neste conteúdo. Exemplo:

LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

Assinatura final

A assinatura final é a concatenação das 3 partes separadas por ("."):

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0.LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

Essas três partes da assinatura, representada pelo exemplo anterior, devem ser enviadas no header Authorization com valor Bearer <assinatura>. Com isso, o e-SiTef poderá validar a assinatura utilizando a chave pública da loja.

Utilizando site JWT para testes

É possível utilizar o site do JWT para criar uma assinatura válida para testes. Para isso é necessário selecionar o algoritmo RS256 e passar o respectivo payload e uma chave pública e privada. "Jwt"

Caso a chave pública não esteja válida a mensagem "Invalid Signature" será exibida. "Jwt"