> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/caf-api-pt-br/connect/authentication/using-mtls.md). # 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](/caf-api/caf-api-pt-br/connect/authentication/certificates/creating-certificate.md) na [Confiança](https://trust.caf.io/) 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 {% hint style="info" %} **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. {% endhint %} ## 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):** ```bash # 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) ```java 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) ```python 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 ```javascript 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: ```bash # 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 ``` {% hint style="info" %} 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. {% endhint %} {% hint style="info" %} Para obter mais informações sobre validade de certificados, renovação e melhores práticas de gerenciamento, consulte [Gerenciamento de certificados](/caf-api/caf-api-pt-br/connect/authentication/certificates/managing-certificate.md). {% endhint %} ## 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`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.caf.io/caf-api/caf-api-pt-br/connect/authentication/using-mtls.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.