Certificates

Certificados são credenciais eletrônicas que incluem identificação e chave pública. Eles podem ser validadas por uma certificadora para maior segurança.

De forma geral, um certificado é um mecanismo que garante uma comunicação segura entre cliente e servidor.

Há dois tipos de certificados subidos ao Manager: certificados para a conexão entre gateway e backend (ou certificados para destination) e certificados para a conexão entre app e gateway (os inbound certificates), estes para uso em ambientes específicos.

Listagem de certificados

A tela de certificados é acessada pela opção Security, dentro do menu principal.

A tela exibe todos os certificados existentes, contendo as seguintes informações sobre eles:

Status: informa se o certificado está ativo (ícone: ) ou expirado (ícone: ).
Name: nome (único) do certificado.
Inbound certificate: informa se o certificado é de uso de ambiente (para conexão entre app e gateway) ou não (em caso negativo, trata-se de um certificado para a conexão entre gateway e backend).
Domain name: informações a respeito do domínio.
Expiration: data e horário de expiração do certificado, em formato mm/dd/aa hh:mm:ss. Certificados com datas passadas já estão expirados, e datas de expiração futuras indicam que são certificados ativos.

Além dessas informações, há duas ações possíveis na coluna Actions: atualizar e deletar um certificado (leia mais sobre isso abaixo).

Cadastrando um certificado

Para cadastrar um certificado, basta clicar no botão Create Certificate, representado pelo símbolo +. Você será direcionado à tela para preenchimento dos dados.

Destination Certificates

Para certificados de uso na conexão entre gateway e backend, não marque a opção Inbound Certificate. As informações a serem passadas são:

Name: campo obrigatório para o nome (único) do certificado.
Certificate Body: campo obrigatório para inserir o corpo do certificado digital de domínio público em formato PEM. Se preferir, o botão Certificate Body pode ser utilizado para fazer upload de um arquivo (.pem ou .crt e não criptografado).
Private Key: campo obrigatório para informar a chave privada, em formato PEM (PKCS #8). A chave não deve possuir senha. Também pode ser passada por upload de arquivo (formato aceito: .key e não criptografado).
- Caso a chave fornecida contenha algum tipo de senha, é possível removê-la. Para isso, copie o arquivo de chave privada em seu diretório OpenSSL e, usando OpenSSL, execute o comando openssl rsa -in privateKey.pem -out newPrivate.pem.
  
  Veja dicas sobre conversão de chaves privadas aqui.
Certificate Chain: campo para inserir a cadeia de certificados que valida a entidade emissora do certificado.
- O campo pode conter uma ou mais unidades certificadoras; cada entrada deve ser separada pelos campos ----BEGIN CERTIFICATE---- e ----END CERTIFICATE----, respectivamente.
- Se preferir, o botão Certificate Chain pode ser utilizado para fazer upload de um arquivo (.pem ou .crt).

Depois de preencher os campos, clique em Save. Você será redirecionado à tela de listagem, que conterá o seu novo certificado.

Inbound Certificates

Para certificados de uso interno de um ambiente, referente à conexão entre apps e gateway, primeiramente marque a opção Inbound Certificate. As informações a serem passadas são:

Name: campo obrigatório para o nome (único) do certificado.
Certificate Body: campo obrigatório para inserir o corpo do certificado digital de domínio público em formato PEM. Se preferir, o botão Certificate Body pode ser utilizado para fazer upload de um arquivo (.pem ou .crt e não criptografado).
- Para inbound certificates, o tamanho mínimo aceito é de 2048 bits.
Private Key: campo obrigatório para informar a chave privada, em formato PEM (PKCS #8). A chave não deve possuir senha. Também pode ser passada por upload de arquivo (formato aceito: .key e não criptografado).
- Caso a chave fornecida contenha algum tipo de senha, é possível removê-la. Para isso, copie o arquivo de chave privada em seu diretório OpenSSL e, usando OpenSSL, execute o comando openssl rsa -in privateKey.pem -out newPrivate.pem.
- Para inbound certificates, o tamanho mínimo aceito é de 2048 bits.
  
  Veja dicas sobre conversão de chaves privadas aqui.
Certificate Chain: campo opcional para inserir a cadeia de certificados que valida a entidade emissora do certificado.
- O campo pode conter uma ou mais unidades certificadoras; cada entrada deve ser separada pelos campos ----BEGIN CERTIFICATE---- e ----END CERTIFICATE----, respectivamente.
- Se preferir, o botão Certificate Chain pode ser utilizado para fazer upload de um arquivo (.pem ou .crt).
Trusted CA: campo onde deve ser incluída a cadeia de certificados (certificate chain) utilizada pelo parceiro ao fazer chamadas ao ambiente. Essa cadeia contém informações sobre o certificado e sobre a autoridade certificadora que o emitiu.
- O campo pode conter uma ou mais cadeias; cada entrada deve ser separada pelos campos ----BEGIN CERTIFICATE---- e ----END CERTIFICATE----, respectivamente.
- Se preferir, o botão Trusted CA pode ser utilizado para fazer upload de um arquivo (.pem ou .crt).
  
  O campo é opcional se TLS for usado e obrigatório no caso de mTLS.

Depois de preencher os campos, clique em Save. Você será redirecionado à tela de listagem, que conterá o seu novo certificado.

Para que um inbound certificate seja aplicado a um ambiente, deverá ser adicionado ao endereço de entrada (inbound address) que servirá como host do ambiente. Nesse caso, se o usuário quiser habilitar a opção de segurança do tipo mTLS para o endereço em questão, será necessário preencher o campo Trusted CA do certificado. Leia sobre como estabelecer um host aqui e sobre como cadastrar um ambiente aqui.

Obtenção de informações de certificado de cliente via header

É possível extrair informações sobre certificados X.509 de clientes via header (x-forwarded-client-cert) em uma conexão com segurança de tipo mTLS.

O header pode ser utilizado em qualquer requisição com conexão mTLS e é possível extrair as informações quando o handshake TLS é bem sucedido (ou seja, quando a etapa de troca de certificados e geração de chaves é concluída). Ele é útil, por exemplo, quando é preciso verificar informações de certificados durante uma chamada de API. As informações que podem ser trafegadas no header são: By, Hash, Cert, Chain, Subject, URI, e DNS.

Nosso time de Engenharia de Produto desenvolveu um custom interceptor (chamado x509 Interceptor) para extrair e manipular dados de certificados X.509 via header x-forwarded-client-cert. Ele pode ser adicionado ao fluxo de requisição de APIs usadas em conexões mTLS. Você pode acessar o código e informações mais detalhadas sobre como utilizá-lo aqui.

Se você tiver uma camada WAF (Web Application Firewall) antes do Gateway da Sensedia, é necessário alterar o nome do header x-forwarded-client-cert para outro nome (por exemplo, forwarded-client-cert). Outra possibilidade é atribuir o valor do certificado a algum outro header antes de encaminhá-lo para o Gateway. Lembrando que, se você tem WAF, você pode: deixar que o WAF trate o mTLS ou TLS ou configurar um bypass para que o Gateway da Sensedia se encarregue dessa atribuição.

Atualizando um certificado

Certificados cadastrados podem ser atualizados pela tela de listagem. Para fazer isso, clique no botão Refresh (ícone: icon refresh ) na linha do certificado desejado.

É possível atualizar certificados expirados e ativos, mesmo que estejam em uso.

Os inbound certificates não podem ser atualizados, apenas deletados.

Após clicar no botão Refresh, uma janela será exibida para confirmar a ação.

Após clicar no botão Confirm, será exibida uma tela igual à de registro de certificados, com os campos a serem alterados.

Para atualizar um certificado, é necessário enviar um novo certificate body, uma nova private key e um novo certificate chain. No entanto, não é possível realizar as seguintes ações:

editar o nome do certificado.
atualizar o certificado sem passar novos certificate body e private key.
atualizar o certificado caso algum dos atributos usados para preencher seus campos no momento da atualização já tenha relação com algum outro certificado cadastrado.

Excluindo um certificado

A exclusão de um certificado é feita de forma simples através do botão Delete (ícone: icon delete ), também localizado na mesma linha do certificado desejado, na listagem de certificados existentes.

Uma janela será exibida para confirmar a ação.

Ao confirmar a ação, o certificado será deletado, não mais aparecendo na listagem.

Não será possível excluir inbound certificates em uso em algum host de ambiente (ou seja, em um endereço de entrada). Se quiser excluir um certificado do tipo, será preciso primeiro removê-lo das configuração do endereço, na tela Inbound Address.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]