Guia de Configuracao SSL, TLS e Proxy do curl

Referencia Rapida das Opcoes SSL e Proxy

curl -k: Ignorar Erros de Certificado SSL

O que faz

A opcao -k (ou --insecure) desativa toda a verificacao de certificados SSL/TLS. O curl nao verificara se o certificado do servidor foi assinado por uma CA de confianca, 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/producao, use --cacert com o certificado CA real — e mais seguro e mais explicito.

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

curl --cacert: Usar um Certificado CA Personalizado

O que faz

A opcao --cacert indica ao curl para verificar o certificado SSL do servidor contra um ficheiro de bundle CA (Certificate Authority) especifico em formato PEM, em vez do repositorio de confianca predefinido do sistema.

Quando usar

Use quando o seu servidor utiliza um certificado assinado por uma CA privada ou interna que nao esta no repositorio de confianca do sistema. Isto e comum em ambientes corporativos, clusters Kubernetes e configuracoes Docker com PKI interna.

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

curl --cert: Certificado de Cliente (TLS Mutuo)

O que faz

A opcao --cert fornece um certificado do lado do cliente para TLS mutuo (mTLS). No mTLS, tanto o servidor como o cliente apresentam certificados para verificar a identidade um do outro. O ficheiro de certificado deve estar em formato PEM ou PKCS#12.

Quando usar

Necessario quando o servidor exige autenticacao por certificado de cliente — comum em APIs bancarias, servicos governamentais, comunicacao de dispositivos IoT e arquiteturas zero-trust. Combine sempre com --key a menos que a chave esteja incorporada no ficheiro do certificado.

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

curl --key: Chave Privada do Certificado de Cliente

O que faz

A opcao --key especifica o ficheiro de chave privada que corresponde ao certificado de cliente fornecido por --cert. A chave deve corresponder ao certificado. Se a chave estiver protegida por palavra-passe, o curl solicitara a frase secreta (ou use --pass).

Quando usar

Use sempre em conjunto com --cert. Se a chave privada ja estiver incorporada no ficheiro de certificado (comum com PKCS#12 / ficheiros .p12), pode omitir --key.

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

curl --tlsv1.2: Forcar TLS 1.2 como Minimo

O que faz

A opcao --tlsv1.2 forca o curl a usar TLS 1.2 como versao minima aceitavel para o handshake SSL/TLS. Protocolos mais antigos (TLS 1.0, 1.1, SSLv3) sao rejeitados.

Quando usar

Use para impor um padrao minimo de seguranca. TLS 1.2 e obrigatorio para conformidade PCI-DSS e e suportado por todos os servidores modernos. A maioria das compilacoes modernas do curl ja usa TLS 1.2+ por defeito, mas esta opcao torna-o explicito.

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

curl --tlsv1.3: Forcar TLS 1.3 como Minimo

O que faz

A opcao --tlsv1.3 forca o curl a usar TLS 1.3 — a versao TLS mais rapida e segura. O TLS 1.3 elimina a viagem de ida e volta extra no handshake (suporte 0-RTT) e remove todos os conjuntos de cifras obsoletos.

Quando usar

Use quando souber que o servidor suporta TLS 1.3 e quiser o melhor desempenho e seguranca. Nota: TLS 1.3 requer OpenSSL 1.1.1+ ou uma biblioteca TLS compativel. Nem todos os servidores o suportam ainda.

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

Opcoes SSL/TLS Adicionais

curl -x: Usar um Proxy HTTP/HTTPS

O que faz

A opcao -x (ou --proxy) encaminha todo o trafego do curl atraves do servidor proxy especificado. O formato e [protocol://]host[:port]. Protocolos de proxy suportados: HTTP, HTTPS, SOCKS4, SOCKS5.

Quando usar

Use para servidores proxy corporativos, depuracao com ferramentas como Fiddler, Charles ou mitmproxy, teste de restricoes geograficas ou quando o acesso direto a internet nao esta disponivel. Tambem pode definir as variaveis de ambiente http_proxy / https_proxy.

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

curl --socks5: Usar um Proxy SOCKS5

O que faz

A opcao --socks5 indica ao curl para usar um proxy SOCKS5 para a ligacao TCP. Ao contrario dos proxies HTTP, o SOCKS5 opera ao nivel TCP e pode lidar com qualquer protocolo — nao apenas HTTP. A resolucao DNS e feita localmente por defeito; use --socks5-hostname para resolver DNS atraves do proxy.

Quando usar

Use para tuneis SSH (ssh -D), acesso a rede Tor ou quando o proxy deve lidar com protocolos nao-HTTP. O SOCKS5 suporta UDP e pode opcionalmente lidar com DNS — tornando-o mais flexivel que proxies HTTP.

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

curl --proxy-user: Autenticacao no Proxy

O que faz

A opcao --proxy-user (ou -U) envia credenciais de autenticacao para o servidor proxy. O formato e user:password. Isto e separado da autenticacao no servidor (-u).

Quando usar

Necessario quando o servidor proxy exige autenticacao — comum em ambientes de rede corporativos e empresariais. As credenciais sao enviadas para o proxy, nao para o servidor de destino.

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

curl --noproxy: Contornar o Proxy para Hosts Especificos

O que faz

A opcao --noproxy especifica uma lista separada por virgulas de hosts, dominios ou enderecos IP que devem contornar o proxy e ligar-se diretamente. Suporta wildcards: *.example.com corresponde a todos os subdominios.

Quando usar

Use para excluir localhost, servicos internos ou dominios especificos do proxy. Isto e importante quando um proxy esta definido globalmente atraves de variaveis de ambiente mas alguns hosts (como servicos locais) precisam de acesso direto. Use * para contornar o proxy para todos os hosts.

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

Opcoes de Proxy Adicionais

curl --resolve: Resolucao DNS Personalizada

O que faz

A opcao --resolve fornece um endereco IP personalizado para um par host:port especifico, contornando completamente a consulta DNS. O formato e host:port:address. Multiplas entradas --resolve podem ser fornecidas.

Quando usar

Essencial para testes antes da propagacao DNS, verificacao de um backend especifico atras de um balanceador de carga ou desenvolvimento local onde precisa de um hostname real para validacao de certificados SSL. Ao contrario de editar /etc/hosts, isto e por pedido e especifico de porta.

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

curl --connect-to: Redirecionar Ligacao para Host Diferente

O que faz

A opcao --connect-to redireciona a ligacao TCP para um par host:port diferente, mantendo o URL original para o pedido HTTP (incluindo o cabecalho Host e SNI). Formato: HOST1:PORT1:HOST2:PORT2.

Quando usar

Use para testar um servidor backend especifico atras de um balanceador de carga sem modificar DNS ou /etc/hosts. Ao contrario de --resolve, isto mapeia host:porta para host:porta (nao para um IP), o que e util quando o destino tambem tem um hostname.

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

Opcoes de Rede Adicionais

Cenarios Reais de SSL e Proxy

Estes exemplos combinam multiplas opcoes para lidar com tarefas comuns de seguranca e rede em ambientes de desenvolvimento, CI/CD e producao.

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

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

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

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

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

Perguntas Frequentes sobre SSL e Proxy no curl