> 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/conectar/authentication/using-mtls.md).

# Usando mTLS

TLS mútuo (mTLS) oferece segurança aprimorada para comunicações de API ao exigir 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 Certta.

## Visão geral

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

1. Cliente inicia uma conexão com a API Certta
2. Servidor Certta apresenta seu certificado
3. Cliente verifica o certificado do servidor
4. Cliente apresenta seu próprio certificado
5. Servidor 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 Certta e que os clientes se conectem somente a servidores Certta legítimos.

## Pré-requisitos

Antes de implementar mTLS, verifique se você tem:

1. Acesso [Criado um certificado](/caf-api/caf-api-pt-br/conectar/authentication/certificates/creating-certificate.md) no [Confiança](https://trust.caf.io/)
2. Baixou seu certificado de cliente (`.crt` arquivo) e tenha sua chave privada (`.key` arquivo)
3. O endpoint correto da API Certta para seu ambiente de produção

{% hint style="info" %}
**Endpoint da API**: Para todas as solicitações de API com mTLS ativado, use a URL base `https://mtls.us.prd.caf.io`. Este é o endpoint de produção que oferece suporte à autenticação TLS mútua.
{% endhint %}

## Implementando mTLS em seu aplicativo

### Convertendo formatos de certificado (se necessário)

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

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

```bash
# Converta .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 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 seus arquivos de certificado e 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 à `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 o 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 repositório de confiança 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 seus arquivos de certificado
cert_file = "certificate.crt"
key_file = "private.key"

# Faça uma requisição à `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 de 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

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

```bash
# Solicitaçã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 carga útil 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 AC não pública.
{% endhint %}

{% hint style="info" %}
Para mais informações sobre validade de certificados, renovação e boas práticas de gerenciamento, consulte [Gerenciando Certificados](/caf-api/caf-api-pt-br/conectar/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**: Verifique se o seu certificado está ativo e não expirou nem foi revogado.
2. **Problemas com a chave privada**: Verifique se a sua chave privada corresponde ao certificado.
3. **Formato incorreto do certificado**: Certifique-se de que está usando o formato correto para sua linguagem/framework.
4. **Problemas com o certificado**: Confirme se o seu certificado ainda é válido e não foi revogado.
5. **Problemas de rede**: Verifique se há firewalls ou proxies interferindo na sua `HTTPS` conexão.

## Melhores 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 de certificados.
* Configure **monitoramento** para expiração de certificados para evitar interrupções no serviço.
* Siga o princípio do **menor privilégio** ao atribuir permissões a 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/caf-api/caf-api-pt-br/conectar/authentication/using-mtls.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
