> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delfinance.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# mTLS
> Detalhes de implementação e operação do mTLS para a API da Delfinance
Esta é a página de detalhes do mTLS. Para a visão geral de autenticação, segurança e quando esse recurso entra em cena, consulte [Autenticação e segurança](/autenticacao/credenciais).
O mTLS (Mutual TLS) é a camada de segurança que valida o certificado do cliente durante o handshake TLS. Em Produção, ele é obrigatório e deve ser usado junto com as credenciais da API.
## Quando é obrigatório
* **Sandbox**: opcional para testes
* **Produção**: obrigatório
## Como funciona
No TLS comum, apenas o servidor prova sua identidade. No mTLS, os dois lados apresentam certificados e validam um ao outro antes de qualquer dado trafegar.
1. O cliente valida o certificado do servidor.
2. O servidor solicita o certificado do cliente.
3. O cliente envia seu certificado assinado.
4. O servidor valida o certificado contra a CA da Delfinance.
5. A conexão segura é estabelecida.
## Processo de emissão do certificado
Crie uma solicitação de certificado com sua chave privada. Veja o passo a passo em [Gerando o CSR com OpenSSL](#gerando-o-csr-com-openssl).
Acesse o portal do desenvolvedor e submeta o arquivo gerado (`requisicao.csr`). Nunca envie a chave privada.
Você receberá o certificado assinado pela CA da Delfinance.
Guarde a chave privada em um cofre seguro, como AWS KMS, HashiCorp Vault ou HSM.
## Gerando o CSR com OpenSSL
O CSR (Certificate Signing Request) é o arquivo que contém sua chave pública e os dados de identificação da sua empresa. Ele é enviado para a Delfinance, que devolve o certificado assinado. O processo tem duas etapas: criar a chave privada e, a partir dela, gerar o CSR.
A chave privada **nunca** deve ser compartilhada, nem com a Delfinance. Se ela vazar, o certificado correspondente precisa ser revogado imediatamente.
### 1. Crie a chave privada
Abra o terminal e execute o comando abaixo para gerar uma chave RSA de 2048 bits:
```bash theme={null}
openssl genpkey -algorithm RSA -out chave-privada.key -pkeyopt rsa_keygen_bits:2048
```
* **`chave-privada.key`**: nome do arquivo em que a chave será salva. Você pode alterá-lo conforme sua convenção.
* **`rsa_keygen_bits:2048`**: tamanho da chave. 2048 bits é o padrão recomendado; 4096 também é aceito, com custo maior de handshake.
Restrinja imediatamente as permissões do arquivo:
```bash theme={null}
chmod 400 chave-privada.key
```
Para proteger a chave com senha (recomendado quando ela não fica em um cofre gerenciado), adicione `-aes-256-cbc` ao comando de geração. Lembre-se de que a aplicação precisará informar essa senha ao abrir a conexão.
### 2. Gere o CSR
Com a chave privada criada, gere a solicitação de certificado:
```bash theme={null}
openssl req -new -key chave-privada.key -out requisicao.csr
```
* **`chave-privada.key`**: a chave privada gerada no passo anterior.
* **`requisicao.csr`**: arquivo em que o CSR será salvo. Use a extensão `.csr`, que é o formato esperado no envio ao portal.
Durante a execução, o OpenSSL solicitará os dados de identificação:
| Campo | Sigla | O que informar |
| - | - | - |
| Country Name | `C` | Código do país com 2 letras - `BR` |
| State or Province Name | `ST` | Estado por extenso - ex.: `Sao Paulo` |
| Locality Name | `L` | Cidade - ex.: `Sao Paulo` |
| Organization Name | `O` | Razão social da empresa, igual ao cadastro na Delfinance |
| Organizational Unit Name | `OU` | Área responsável - ex.: `Tecnologia` |
| Common Name | `CN` | Identificador do cliente (domínio ou nome da integração) |
| Email Address | - | Opcional; pode ser deixado em branco |
O campo `challenge password` pode ser deixado em branco (pressione Enter). Evite caracteres acentuados nos demais campos, pois eles podem gerar falhas na emissão.
### 3. Alternativa: gerar tudo em um comando
Para automatizar (pipelines, scripts de provisionamento), use `-subj` e evite o modo interativo:
```bash theme={null}
openssl req -new -newkey rsa:2048 -nodes \
-keyout chave-privada.key \
-out requisicao.csr \
-subj "/C=BR/ST=Sao Paulo/L=Sao Paulo/O=Minha Empresa LTDA/OU=Tecnologia/CN=integracao.minhaempresa.com.br"
```
O parâmetro `-nodes` gera a chave sem senha. Use apenas quando a chave for armazenada em um cofre com controle de acesso (KMS, Vault, HSM).
### 4. Confira o conteúdo antes de enviar
Valide os dados e a assinatura do CSR:
```bash theme={null}
openssl req -in requisicao.csr -noout -text -verify
```
Confirme se `Subject` traz exatamente os dados da sua empresa e se `Public-Key` indica o tamanho esperado (`2048 bit`).
### Resultado
Ao final você terá dois arquivos:
* **`chave-privada.key`**: sua chave privada. Deve ser mantida em segredo e **NUNCA** compartilhada, nem conosco.
* **`requisicao.csr`**: o CSR a ser enviado no portal do desenvolvedor da Delfinance.
## Exemplo de uso
```bash theme={null}
curl https://api.delbank.com.br/baas/api/v1/balances \
--cert ./certificado.pem \
--key ./chave-privada.key \
-H "x-delbank-api-key: SUA_API_KEY" \
-H "x-delfinance-account-id: SUA_ACCOUNT_ID"
```
Para montar o cliente na sua linguagem (Node.js, Python, C#, Java, PHP, Go) e configurar o Postman, veja [Exemplos de Conexão](/autenticacao/exemplos-conexao).
## Boas práticas
* nunca versione a chave privada em repositórios;
* gere um par de chaves distinto para Sandbox e para Produção;
* rotacione certificados antes do vencimento;
* teste a cadeia de confiança em ambiente de homologação;
* monitore falhas de handshake para detectar tentativas suspeitas.
## Erros comuns
| Erro | Causa |
| - | - |
| `SSL certificate problem: unable to get local issuer` | CA não confiável ou certificado incompleto |
| `alert bad certificate` | Certificado expirado ou revogado |
| `handshake failure` | Cipher suite ou versão TLS incompatível |
| `certificate verify failed` | Certificado não corresponde ao cadastrado |
| `key values mismatch` | O certificado enviado não corresponde à chave privada usada na requisição |