Usando mTLS

TLS mútuo (mTLS) oferece segurança aprimorada para comunicações de API, exigindo que tanto o cliente quanto o servidor se autentiquem mutuamente usando certificados X.509. Este guia explica como usar seus certificados Certta para estabelecer conexões mTLS com as APIs da Certta.

Visão geral

No TLS tradicional, apenas o servidor se autentica para o cliente. No mTLS, ambas as partes se autenticam mutuamente:

1. Cliente inicia uma conexão com a API da Certta
2. Servidor da Certta apresenta seu certificado
3. Cliente verifica o certificado do servidor
4. Cliente apresenta seu próprio certificado
5. Servidor da Certta verifica o certificado do cliente
6. Se ambas as verificações forem bem-sucedidas, uma conexão segura é estabelecida

Essa autenticação bidirecional garante que apenas clientes confiáveis possam acessar as APIs da Certta, e que os clientes se conectem apenas a servidores legítimos da Certta.

Pré-requisitos

Antes de implementar mTLS, certifique-se de que você tem:

1. Acesso Criado um certificado na Confiança
2. baixado seu certificado de cliente (.crt arquivo) e possui sua chave privada (.key arquivo)
3. O endpoint de API correto da Certta para seu ambiente de produção

Endpoint da API: Para todas as solicitações de API habilitadas para mTLS, use a URL base https://mtls.us.prd.caf.io. Este é o endpoint de produção que oferece suporte à autenticação mútua por TLS.

Implementando mTLS em seu aplicativo

Convertendo formatos de certificado (se necessário)

Dependendo da sua linguagem de programação e framework, talvez seja necessário converter o formato do seu certificado:

Convertendo .crt para outros formatos (se necessário):

# Converter .crt para .pem (se necessário)
# Em muitos casos, .crt e .pem são compatíveis, mas algumas bibliotecas preferem extensões específicas
cp certificate.crt certificate.pem

# Se você precisar combinar o certificado e a chave privada no formato PKCS#12 (.p12)
openssl pkcs12 -export -out certificate.p12 -inkey private.key -in certificate.crt

Exemplos de código

Abaixo estão exemplos de implementação de mTLS em várias linguagens de programação:

Java (OkHttp)

import okhttp3.OkHttpClient;
import okhttp3.Request;

import javax.net.ssl.*;
import java.io.FileInputStream;
import java.io.IOException;
import java.security.*;
import java.security.cert.CertificateException;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.PKCS8EncodedKeySpec;

public class MtlsClient {
    public static void main(String[] args) throws Exception {
        // Carregue os arquivos do seu certificado e da sua chave privada
        X509Certificate certificate = loadCertificate("certificate.crt");
        PrivateKey privateKey = loadPrivateKey("private.key");

        // Crie um KeyManager com seu certificado e chave privada
        KeyManager[] keyManagers = createKeyManagers(certificate, privateKey);

        // Crie um TrustManager que confie no certificado do servidor
        TrustManager[] trustManagers = createTrustManagers();

        // Crie um contexto SSL com os gerenciadores de chave e confiança
        SSLContext sslContext = SSLContext.getInstance("TLS");
        sslContext.init(keyManagers, trustManagers, new SecureRandom());

        // Crie um OkHttpClient com o contexto SSL
        OkHttpClient client = new OkHttpClient.Builder()
                .sslSocketFactory(sslContext.getSocketFactory(), (X509TrustManager) trustManagers[0])
                .build();

        // Faça uma requisição para a `API`
        Request request = new Request.Builder()
                .url("https://mtls.us.prd.caf.io/v1/transactions")
                .build();

        client.newCall(request).execute();
    }

    private static X509Certificate loadCertificate(String filename) throws CertificateException, IOException {
        CertificateFactory factory = CertificateFactory.getInstance("X.509");
        try (FileInputStream fis = new FileInputStream(filename)) {
            return (X509Certificate) factory.generateCertificate(fis);
        }
    }

    private static PrivateKey loadPrivateKey(String filename) throws IOException, NoSuchAlgorithmException, InvalidKeySpecException {
        // Leia o arquivo da chave privada (pressupõe formato PKCS#8)
        byte[] keyBytes = java.nio.file.Files.readAllBytes(java.nio.file.Paths.get(filename));
        PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(keyBytes);
        KeyFactory kf = KeyFactory.getInstance("RSA");
        return kf.generatePrivate(spec);
    }

    private static KeyManager[] createKeyManagers(X509Certificate certificate, PrivateKey privateKey) throws Exception {
        KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
        keyStore.load(null, null);
        keyStore.setCertificateEntry("certificate", certificate);
        keyStore.setKeyEntry("private-key", privateKey, new char[0], new java.security.cert.Certificate[]{certificate});

        KeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
        kmf.init(keyStore, new char[0]);
        return kmf.getKeyManagers();
    }

    private static TrustManager[] createTrustManagers() throws Exception {
        // Para uso em produção, você deve usar um trust store adequado
        return new TrustManager[] {
            new X509TrustManager() {
                public X509Certificate[] getAcceptedIssuers() { return new X509Certificate[0]; }
                public void checkClientTrusted(X509Certificate[] certs, String authType) {}
                public void checkServerTrusted(X509Certificate[] certs, String authType) {}
            }
        };
    }
}

Python (Requests)

import requests

# Caminho para os arquivos do seu certificado
cert_file = "certificate.crt"
key_file = "private.key"

# Faça uma requisição para a `API`
response = requests.get(
    "https://mtls.us.prd.caf.io/v1/transactions",
    cert=(cert_file, key_file)
)

print(response.json())

Node.js

const https = require("https");
const fs = require("fs");

// Leia os arquivos do certificado
const cert = fs.readFileSync("certificate.crt");
const key = fs.readFileSync("private.key");

// Configure as opções da requisição
const options = {
  hostname: "mtls.us.prd.caf.io",
  port: 443,
  path: "/v1/transactions",
  method: "GET",
  cert: cert,
  key: key,
};

// Faça a requisição
const req = https.request(options, (res) => {
  let data = "";
  res.on("data", (chunk) => {
    data += chunk;
  });
  res.on("end", () => {
    console.log(JSON.parse(data));
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

cURL

Testes mTLS conexões pela linha de comando podem ser úteis para depuração. Veja como usar o curl com mTLS certificados:

# Requisição básica `mTLS`
curl --cert certificate.crt --key private.key https://mtls.us.prd.caf.io/v1/transactions

# Com opções adicionais
curl --cert certificate.crt \\
     --key private.key \\
     --cacert ca.crt \\
     -H "Content-Type: application/json" \\
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \\
     https://mtls.us.prd.caf.io/v1/transactions

# Com payload de dados
curl --cert certificate.crt \\
     --key private.key \\
     --cacert ca.crt \\
     -X POST \\
     -H "Content-Type: application/json" \\
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \\
     -d '{"key1": "value1", "key2": "value2"}' \\
     https://mtls.us.prd.caf.io/v1/transactions

Ao usar o curl para testes, talvez você precise fornecer a cadeia completa de certificados usando a --cert opção ou especificar a autoridade certificadora com --cacert se você estiver usando uma CA não pública.

Para obter mais informações sobre validade de certificados, renovação e melhores práticas de gerenciamento, consulte Gerenciamento de certificados.

Solução de problemas mTLS conexões

Se você encontrar problemas com sua mTLS conexão, considere as seguintes etapas de solução de problemas:

1. Falha na validação do certificado: Certifique-se de que seu certificado esteja ativo e não expirado ou revogado.
2. Problemas com a chave privada: Verifique se sua chave privada corresponde ao certificado.
3. Formato incorreto do certificado: Certifique-se de que você está usando o formato correto para sua linguagem/framework.
4. Problemas com o certificado: Confirme que seu certificado ainda é válido e não foi revogado.
5. Problemas de rede: Verifique se há firewalls ou proxies interferindo em sua HTTPS conexão.

Boas práticas

• Mantenha certificados e chaves privadas seguros no ambiente de implantação do seu aplicativo.
• Use armazenamento seguro para arquivos de certificado em seus ambientes de implantação.
• Implemente procedimentos de rotação de certificados para lidar com a expiração dos certificados.
• Configure monitoramento da expiração dos certificados para evitar interrupções no serviço.
• Siga o princípio do menor privilégio ao atribuir permissões aos serviços usando mTLS.