Guia de configuração curl SSL, TLS e proxy

Q: Como pular a verificação de certificado SSL no curl?

Use curl -k URL ou curl --insecure URL. Isso desabilita todas as verificações de certificado — expiração, incompatibilidade de hostname, CA não confiável. Use apenas para desenvolvimento local. Para produção, use --cacert com o certificado CA real.

Q: Como fazer o curl confiar em um certificado autoassinado?

Use curl --cacert /caminho/para/ca.pem URL para especificar o certificado CA que assinou seu certificado autoassinado. É mais seguro que -k porque ainda valida a cadeia de certificados — confiando apenas na sua CA específica.

Q: Como verificar qual versão TLS o curl está usando?

Execute curl -v URL e procure pela linha * SSL connection using TLSv1.x / CipherSuite na saída detalhada. Para forçar uma versão específica, use --tlsv1.2 ou --tlsv1.3.

Q: O que é TLS mútuo (mTLS) e como usá-lo com curl?

TLS mútuo requer que ambos servidor e cliente apresentem certificados. Use: curl --cert client.pem --key client-key.pem --cacert server-ca.pem URL. O par --cert/--key autentica o cliente; --cacert verifica o servidor.

Q: Como usar curl através de um proxy HTTP?

Use curl -x http://proxy:porta URL. Para proxy HTTPS: curl -x https://proxy:porta URL. Alternativamente, defina as variáveis de ambiente http_proxy e https_proxy — o curl as detecta automaticamente.

Q: Como usar curl com proxy SOCKS5?

Use curl --socks5 host:porta URL para resolução DNS local, ou curl --socks5-hostname host:porta URL para resolver DNS pelo proxy (importante para privacidade/Tor). Exemplo com túnel SSH: ssh -D 1080 user@bastion, depois curl --socks5 localhost:1080 URL.

Q: Como autenticar com um servidor proxy no curl?

Use curl -x http://proxy:porta -U user:senha URL. A flag -U (ou --proxy-user) envia credenciais para o proxy. Isso é separado de -u, que autentica com o servidor de destino.

Q: Como excluir certos hosts do proxy no curl?

Use --noproxy "localhost,127.0.0.1,*.internal.com" ou defina a variável de ambiente NO_PROXY. Suporta curingas (*.example.com). Use --noproxy "*" para ignorar o proxy completamente para uma única requisição.

Q: Como testar HTTPS no localhost com curl?

Para teste rápido: curl -k https://localhost:8443/. Para validação adequada: curl --resolve myapp.local:443:127.0.0.1 --cacert local-ca.pem https://myapp.local/. A abordagem --resolve permite que o hostname do certificado corresponda corretamente.

Q: Como substituir a resolução DNS para um host específico no curl?

Use curl --resolve host:porta:IP URL. Exemplo: curl --resolve api.example.com:443:192.168.1.100 https://api.example.com/. Isso ignora o DNS apenas para aquele par host:porta — sem necessidade de editar /etc/hosts.

Configurar certificados HTTPS, versões TLS, proxies e resolução DNS personalizada no curl é essencial para comunicação segura de API, pipelines CI/CD e depuração de problemas de rede. Este guia cobre todas as flags de SSL, TLS, proxy e rede — desde desabilitar verificações de certificado com -k para desenvolvimento local até configurar TLS mútuo com --cert e rotear tráfego através de proxies SOCKS5. Cada opção inclui uma explicação clara, considerações de segurança e um exemplo pronto para copiar.

Referência rápida de flags SSL e proxy

Flag	Categoria	Descrição
-k	SSL/TLS	Permitir conexões inseguras — pular toda verificação SSL
--cacert	SSL/TLS	Verificar o certificado do servidor contra um bundle CA específico
--cert	SSL/TLS	Fornecer certificado do cliente para autenticação TLS mútua
--key	SSL/TLS	Fornecer o arquivo de chave privada para o certificado do cliente
--tlsv1.2	SSL/TLS	Usar TLS versão 1.2 ou superior para a conexão
--tlsv1.3	SSL/TLS	Usar TLS versão 1.3 ou superior para a conexão
--ssl-reqd	SSL/TLS	Exigir SSL/TLS para a conexão (falhar se não disponível)
--ciphers	SSL/TLS	Especificar quais cifras SSL usar para a conexão
--cert-type	SSL/TLS	Especificar o tipo de certificado do cliente (PEM, DER, ENG, P12)
--pinnedpubkey	SSL/TLS	Fixar e verificar a chave pública do servidor (estilo HPKP)
-x	Proxy	Rotear todo tráfego pelo servidor proxy especificado
--socks5	Proxy	Rotear a conexão através de um proxy SOCKS5
--proxy-user	Proxy	Fornecer usuário:senha para o servidor proxy
--noproxy	Proxy	Lista de hosts que não devem passar pelo proxy
--socks5-hostname	Proxy	Proxy SOCKS5 com resolução DNS pelo proxy
--proxy-cacert	Proxy	Certificado CA para verificar o próprio proxy HTTPS
--resolve	Rede	Mapear um par host:porta específico para um endereço IP personalizado
--connect-to	Rede	Conectar a um host:porta diferente do que a URL especifica
--local-port	Rede	Definir número da porta local ou intervalo para a conexão
--interface	Rede	Vincular a conexão a uma interface de rede específica
--dns-servers	Rede	Usar servidores DNS personalizados em vez dos padrões do sistema (c-ares)

-kSSL/TLS

Permitir conexões inseguras — pular toda verificação SSL

--cacertSSL/TLS

Verificar o certificado do servidor contra um bundle CA específico

--certSSL/TLS

Fornecer certificado do cliente para autenticação TLS mútua

--keySSL/TLS

Fornecer o arquivo de chave privada para o certificado do cliente

--tlsv1.2SSL/TLS

Usar TLS versão 1.2 ou superior para a conexão

--tlsv1.3SSL/TLS

Usar TLS versão 1.3 ou superior para a conexão

--ssl-reqdSSL/TLS

Exigir SSL/TLS para a conexão (falhar se não disponível)

--ciphersSSL/TLS

Especificar quais cifras SSL usar para a conexão

--cert-typeSSL/TLS

Especificar o tipo de certificado do cliente (PEM, DER, ENG, P12)

--pinnedpubkeySSL/TLS

Fixar e verificar a chave pública do servidor (estilo HPKP)

-xProxy

Rotear todo tráfego pelo servidor proxy especificado

--socks5Proxy

Rotear a conexão através de um proxy SOCKS5

--proxy-userProxy

Fornecer usuário:senha para o servidor proxy

--noproxyProxy

Lista de hosts que não devem passar pelo proxy

--socks5-hostnameProxy

Proxy SOCKS5 com resolução DNS pelo proxy

--proxy-cacertProxy

Certificado CA para verificar o próprio proxy HTTPS

--resolveRede

Mapear um par host:porta específico para um endereço IP personalizado

--connect-toRede

Conectar a um host:porta diferente do que a URL especifica

--local-portRede

Definir número da porta local ou intervalo para a conexão

--interfaceRede

Vincular a conexão a uma interface de rede específica

--dns-serversRede

Usar servidores DNS personalizados em vez dos padrões do sistema (c-ares)

curl -k: Ignorar erros de certificado SSL

O que faz: A flag -k (ou --insecure) desabilita toda verificação de certificado SSL/TLS. O curl não verificará se o certificado do servidor é assinado por uma CA confiável, se o hostname corresponde ou se o certificado expirou.
Quando usar: Use apenas para desenvolvimento local com certificados autoassinados ou ambientes de teste. Para staging/produção, use --cacert com o certificado CA real — é mais seguro e mais explícito.

$ curl -k https://localhost:8443/api/health

Nunca use -k em scripts de produção ou pipelines CI/CD. Ele desabilita toda validação de certificado, tornando sua conexão vulnerável a ataques man-in-the-middle. Use --cacert para confiar em uma CA específica.

curl --cacert: Usar certificado CA personalizado

O que faz: A flag --cacert instrui o curl a verificar o certificado SSL do servidor contra um arquivo de bundle CA (Certificate Authority) específico em formato PEM, em vez do armazenamento de confiança padrão do sistema.
Quando usar: Use quando seu servidor usa um certificado assinado por uma CA privada ou interna que não está no armazenamento de confiança do sistema. Isso é comum em ambientes corporativos, clusters Kubernetes e configurações Docker com PKI interna.

$ curl --cacert /path/to/corporate-ca.pem https://internal-api.example.com/data

curl --cert: Certificado do cliente (TLS mútuo)

O que faz: A flag --cert fornece um certificado do lado do cliente para TLS mútuo (mTLS). No mTLS, tanto o servidor quanto o cliente apresentam certificados para verificar a identidade um do outro. O arquivo de certificado deve estar em formato PEM ou PKCS#12.
Quando usar: Necessário quando o servidor exige autenticação por certificado do cliente — comum em APIs bancárias, serviços governamentais, comunicação de dispositivos IoT e arquiteturas zero-trust. Sempre combine com --key, a menos que a chave esteja incorporada no arquivo de certificado.

$ curl --cert client.pem --key client-key.pem https://mtls-api.example.com/secure

curl --key: Chave privada do certificado do cliente

O que faz: A flag --key especifica o arquivo de chave privada que faz par com o certificado do cliente fornecido por --cert. A chave deve corresponder ao certificado. Se a chave for protegida por senha, o curl solicitará a frase secreta (ou use --pass).
Quando usar: Sempre use junto com --cert. Se a chave privada já estiver incorporada no arquivo de certificado (comum com PKCS#12 / arquivos .p12), você pode omitir --key.

$ curl --cert client.pem --key client-key.pem --cacert server-ca.pem https://api.example.com/secure

curl --tlsv1.2: Forçar TLS 1.2 mínimo

O que faz: A flag --tlsv1.2 força o curl a usar TLS 1.2 como versão mínima aceitável para o handshake SSL/TLS. Protocolos mais antigos (TLS 1.0, 1.1, SSLv3) são rejeitados.
Quando usar: Use para impor um padrão mínimo de segurança. TLS 1.2 é necessário para conformidade PCI-DSS e é suportado por todos os servidores modernos. A maioria dos builds modernos do curl já usa TLS 1.2+ por padrão, mas esta flag torna isso explícito.

$ curl --tlsv1.2 -v https://secure.example.com/api 2>&1 | grep 'SSL connection'

curl --tlsv1.3: Forçar TLS 1.3 mínimo

O que faz: A flag --tlsv1.3 força o curl a usar TLS 1.3 — a versão TLS mais rápida e segura. TLS 1.3 elimina o round-trip extra no handshake (suporte 0-RTT) e remove todas as suítes de cifra obsoletas.
Quando usar: Use quando souber que o servidor suporta TLS 1.3 e quiser o melhor desempenho e segurança. Nota: TLS 1.3 requer OpenSSL 1.1.1+ ou uma biblioteca TLS compatível. Nem todos os servidores suportam isso ainda.

$ curl --tlsv1.3 https://modern-api.example.com/data

Opções SSL/TLS adicionais

Flag	Descrição
--ssl-reqd	Exigir SSL/TLS para a conexão (falhar se não disponível)
--ciphers	Especificar quais cifras SSL usar para a conexão
--cert-type	Especificar o tipo de certificado do cliente (PEM, DER, ENG, P12)
--pinnedpubkey	Fixar e verificar a chave pública do servidor (estilo HPKP)

--ssl-reqd

Exigir SSL/TLS para a conexão (falhar se não disponível)

--ciphers

Especificar quais cifras SSL usar para a conexão

--cert-type

Especificar o tipo de certificado do cliente (PEM, DER, ENG, P12)

--pinnedpubkey

Fixar e verificar a chave pública do servidor (estilo HPKP)

curl -x: Usar proxy HTTP/HTTPS

O que faz: A flag -x (ou --proxy) roteia todo tráfego curl pelo servidor proxy especificado. O formato é [protocolo://]host[:porta]. Protocolos de proxy suportados: HTTP, HTTPS, SOCKS4, SOCKS5.
Quando usar: Use para servidores proxy corporativos, depuração com ferramentas como Fiddler, Charles ou mitmproxy, teste de restrições geográficas ou quando o acesso direto à internet não está disponível. Você também pode definir as variáveis de ambiente http_proxy / https_proxy.

$ curl -x http://proxy.example.com:8080 https://api.example.com/data

curl --socks5: Usar proxy SOCKS5

O que faz: A flag --socks5 instrui o curl a usar um proxy SOCKS5 para a conexão TCP. Diferente dos proxies HTTP, SOCKS5 opera no nível TCP e pode lidar com qualquer protocolo — não apenas HTTP. A resolução DNS é feita localmente por padrão; use --socks5-hostname para resolver DNS pelo proxy.
Quando usar: Use para túneis SSH (ssh -D), acesso à rede Tor ou quando o proxy precisa lidar com protocolos não-HTTP. SOCKS5 suporta UDP e pode opcionalmente lidar com DNS — tornando-o mais flexível que proxies HTTP.

$ curl --socks5 localhost:1080 https://api.example.com/data

curl --proxy-user: Autenticação de proxy

O que faz: A flag --proxy-user (ou -U) envia credenciais de autenticação para o servidor proxy. O formato é user:password. Isso é separado da autenticação do servidor (-u).
Quando usar: Necessário quando o servidor proxy exige autenticação — comum em ambientes de rede corporativos e empresariais. As credenciais são enviadas para o proxy, não para o servidor de destino.

$ curl -x http://proxy.corp.com:3128 -U user:pass https://external-api.com/data

curl --noproxy: Ignorar proxy para hosts específicos

O que faz: A flag --noproxy especifica uma lista separada por vírgulas de hosts, domínios ou endereços IP que devem ignorar o proxy e conectar diretamente. Suporta curingas: *.example.com corresponde a todos os subdomínios.
Quando usar: Use para excluir localhost, serviços internos ou domínios específicos do proxy. Isso é importante quando um proxy está configurado globalmente via variáveis de ambiente, mas alguns hosts (como serviços locais) precisam de acesso direto. Use * para ignorar o proxy para todos os hosts.

$ curl -x http://proxy:8080 --noproxy "localhost,127.0.0.1,*.internal.com" https://localhost:3000/api

Opções de proxy adicionais

Flag	Descrição
--socks5-hostname	Proxy SOCKS5 com resolução DNS pelo proxy
--proxy-cacert	Certificado CA para verificar o próprio proxy HTTPS

--socks5-hostname

Proxy SOCKS5 com resolução DNS pelo proxy

--proxy-cacert

Certificado CA para verificar o próprio proxy HTTPS

curl --resolve: Resolução DNS personalizada

O que faz: A flag --resolve fornece um endereço IP personalizado para um par host:porta específico, ignorando completamente a consulta DNS. O formato é host:port:address. Múltiplas entradas --resolve podem ser fornecidas.
Quando usar: Essencial para testes antes da propagação DNS, verificação de um backend específico atrás de um balanceador de carga ou desenvolvimento local onde você precisa de um hostname real para validação de certificado SSL. Diferente de editar /etc/hosts, isso é por requisição e específico por porta.

$ curl --resolve api.example.com:443:127.0.0.1 https://api.example.com/health

curl --connect-to: Redirecionar conexão para host diferente

O que faz: A flag --connect-to redireciona a conexão TCP para um par host:porta diferente mantendo a URL original para a requisição HTTP (incluindo o header Host e SNI). Formato: HOST1:PORTA1:HOST2:PORTA2.
Quando usar: Use para testar um servidor backend específico atrás de um balanceador de carga sem modificar DNS ou /etc/hosts. Diferente de --resolve, isso mapeia host:porta para host:porta (não para um IP), o que é útil quando o destino também tem um hostname.

$ curl --connect-to api.example.com:443:backend1.internal:8443 https://api.example.com/health

Opções de rede adicionais

Flag	Descrição
--local-port	Definir número da porta local ou intervalo para a conexão
--interface	Vincular a conexão a uma interface de rede específica
--dns-servers	Usar servidores DNS personalizados em vez dos padrões do sistema (c-ares)

--local-port

Definir número da porta local ou intervalo para a conexão

--interface

Vincular a conexão a uma interface de rede específica

--dns-servers

Usar servidores DNS personalizados em vez dos padrões do sistema (c-ares)

Cenários reais de SSL e proxy

Estes exemplos combinam múltiplas flags para lidar com tarefas comuns de segurança e rede em ambientes de desenvolvimento, CI/CD e produção.

Testando HTTPS no localhost

Ao desenvolver localmente com certificado autoassinado, combine --resolve com --cacert (ou -k para testes rápidos). Isso permite usar um hostname real para SSL/SNI adequado sem modificar seu arquivo hosts.

$ curl --resolve myapp.local:443:127.0.0.1 --cacert local-ca.pem https://myapp.local/api/status

TLS mútuo (autenticação por certificado do cliente)

Algumas APIs exigem que tanto servidor quanto cliente apresentem certificados. Forneça --cert, --key e --cacert para estabelecer uma conexão TLS bidirecional totalmente verificada.

$ curl --cert client.pem --key client-key.pem --cacert server-ca.pem https://mtls-api.example.com/data

Proxy corporativo com autenticação

Em redes corporativas com servidores proxy obrigatórios, combine -x com -U para credenciais de proxy. Adicione --noproxy para excluir serviços internos do proxy.

$ curl -x http://proxy.corp.com:3128 -U user:pass --noproxy "*.internal.corp" https://external-api.com/data

Container Docker com CA interna

Quando serviços no Docker usam certificados de uma CA interna, monte o certificado CA no container e referencie-o com --cacert. Isso é mais seguro que -k porque ainda valida a cadeia de certificados.

$ curl --cacert /etc/ssl/certs/internal-ca.crt https://service.docker.internal:8443/health

Proxy SOCKS5 via túnel SSH

Crie um proxy SOCKS5 com ssh -D e roteie o tráfego curl através dele usando --socks5. Útil para acessar serviços internos através de um host bastion.

$ curl --socks5 localhost:1080 https://internal-api.example.com/status

Perguntas frequentes sobre curl SSL e proxy

Como pular a verificação de certificado SSL no curl?

Use curl -k URL ou curl --insecure URL. Isso desabilita todas as verificações de certificado — expiração, incompatibilidade de hostname, CA não confiável. Use apenas para desenvolvimento local. Para produção, use --cacert com o certificado CA real.

Como fazer o curl confiar em um certificado autoassinado?

Use curl --cacert /caminho/para/ca.pem URL para especificar o certificado CA que assinou seu certificado autoassinado. É mais seguro que -k porque ainda valida a cadeia de certificados — confiando apenas na sua CA específica.

Como verificar qual versão TLS o curl está usando?

Execute curl -v URL e procure pela linha * SSL connection using TLSv1.x / CipherSuite na saída detalhada. Para forçar uma versão específica, use --tlsv1.2 ou --tlsv1.3.

O que é TLS mútuo (mTLS) e como usá-lo com curl?

TLS mútuo requer que ambos servidor e cliente apresentem certificados. Use: curl --cert client.pem --key client-key.pem --cacert server-ca.pem URL. O par --cert/--key autentica o cliente; --cacert verifica o servidor.

Como usar curl através de um proxy HTTP?

Use curl -x http://proxy:porta URL. Para proxy HTTPS: curl -x https://proxy:porta URL. Alternativamente, defina as variáveis de ambiente http_proxy e https_proxy — o curl as detecta automaticamente.

Como usar curl com proxy SOCKS5?

Use curl --socks5 host:porta URL para resolução DNS local, ou curl --socks5-hostname host:porta URL para resolver DNS pelo proxy (importante para privacidade/Tor). Exemplo com túnel SSH: ssh -D 1080 user@bastion, depois curl --socks5 localhost:1080 URL.

Como autenticar com um servidor proxy no curl?

Use curl -x http://proxy:porta -U user:senha URL. A flag -U (ou --proxy-user) envia credenciais para o proxy. Isso é separado de -u, que autentica com o servidor de destino.

Como excluir certos hosts do proxy no curl?

Use --noproxy "localhost,127.0.0.1,*.internal.com" ou defina a variável de ambiente NO_PROXY. Suporta curingas (*.example.com). Use --noproxy "*" para ignorar o proxy completamente para uma única requisição.

Como testar HTTPS no localhost com curl?

Para teste rápido: curl -k https://localhost:8443/. Para validação adequada: curl --resolve myapp.local:443:127.0.0.1 --cacert local-ca.pem https://myapp.local/. A abordagem --resolve permite que o hostname do certificado corresponda corretamente.

Como substituir a resolução DNS para um host específico no curl?

Use curl --resolve host:porta:IP URL. Exemplo: curl --resolve api.example.com:443:192.168.1.100 https://api.example.com/. Isso ignora o DNS apenas para aquele par host:porta — sem necessidade de editar /etc/hosts.

Como corrigir 'SSL certificate problem: certificate has expired' no curl?

O certificado do servidor expirou. Soluções: (1) Renove o certificado no servidor, (2) Atualize seu bundle CA: curl --cacert /caminho/para/ca-atualizado.pem URL, (3) Apenas para testes: curl -k URL. Verificar expiração: curl -v URL 2>&1 | grep expire.

É seguro usar curl --insecure (-k) em produção?

Não. A flag -k desabilita toda validação de certificado — expiração, hostname e cadeia de confiança. Isso torna sua conexão vulnerável a ataques man-in-the-middle. Sempre use --cacert com o certificado CA específico em produção e pipelines CI/CD.