Ir para o conteúdo

Uso de certificados digitais para autenticação SSL

O Renave WS exige autenticação SSL (https). Por conta disso, os clientes devem utilizar certificados digitais de máquina para conseguir realizar as requisições.

Cada cliente (estabelecimento) deve ter seu certificado previamente cadastrado no banco de dados do Credencia Denatran. Neste cadastro constam os seguintes dados do certificado digital:

  • serial
  • common name
  • common name do emissor

Essa autenticação SSL é two-way, ou seja, a aplicação cliente também deve confiar no servidor do web service. Sendo assim, as cadeias da autoridade certificadora SERPRO (de homologação ou de produção, dependendo do caso) devem estar presentes no truststore da aplicação cliente.

Requisito de protocolo

Obrigatório protocolo TLSv1 ou superior.

Exemplo de chamada curl usando certificado digital

curl -v --insecure --cert certificado-publico-com-cadeia.pem --key chave-privada.key -nodes GET "https://hom.emplaca.estaleiro.serpro.gov.br/emplaca-ws/api-estampador/municipios/7107" "accept: /"

Extraindo partes pública (.pem) e privada (.key) a partir de um PKCS12 (.p12)

Para extrair chave privada:

openssl pkcs12 -in certificado.p12 -out chave-privada.key -nocerts -nodes

Para extrair a parte pública (incluindo a cadeia de autoridades certificadoras):

openssl pkcs12 -in certificado.p12 -out saida.txt

Abrir o arquivo saida.txt em um editor de texto e remover a chave privada. Salvar isso como certificado-publico-com-cadeia.pem.

Segurança

Lembre-se de proteger adequadamente seu certificado digital de produção! A chave privada deve residir apenas em um servidor bem protegido. Não utilize o certificado digital de produção para o desenvolvimento!

Verificação CN vs host

Assim como o Renave WS valida o certificado utilizado pelo cliente, também é esperado que o cliente valide o certificado com algumas verificações, como a verificação da cadeia do certificado e a verificação do vencimento do certificado. Esse tipo de verificação costuma já estar embutida nas bibliotecas de conexão SSL.

Caso a aplicação cliente receba um erro parecido com "No subject alternative DNS name matching hom.renave.estaleiro.serpro.gov.br found" isso se deve a uma outra verificação feita pelas bibliotecas, a conferência entre CN (common name) do certificado do serviço (Renave WS) e o host (endereço) sendo acessado.

Se esse problema ocorrer em homologação, a aplicação cliente deve ou desabilitar essa verificação para o ambiente de homologação ou então implementar uma verificação personalizada (a de que o host deve ser hom.renave.estaleiro.serpro.gov.br e o CN do certificado deve ser estaleiro.serpro.gov.br).

Esse problema não deve ocorrer em produção.

Como implementar essa verificação de forma personalizada depende da linguagem de programação e da biblioteca REST/HTTP/SSL que estiver usando. A título de exemplo, uma forma de personalizar essa validação no Java seria: '' HttpsURLConnection.setDefaultHostnameVerifier( new HostnameVerifier() { @Override public boolean verify(String hostname, SSLSession session) { return true; } }); ''

Atenção: esse exemplo é fornecido sem garantia de funcionamento, apenas para dar uma ideia de como pode ser a solução.