curl SSL, TLS & Proxy Configuration Guide

Q: How do I skip SSL certificate verification in curl?

Use curl -k URL or curl --insecure URL. This disables all certificate checks — expiration, hostname mismatch, untrusted CA. Use only for local development. For production, use --cacert with the actual CA certificate.

Q: How do I make curl trust a self-signed certificate?

Use curl --cacert /path/to/ca.pem URL to specify the CA certificate that signed your self-signed cert. This is safer than -k because it still validates the certificate chain — only trusting your specific CA.

Q: How do I check which TLS version curl is using?

Run curl -v URL and look for the line * SSL connection using TLSv1.x / CipherSuite in the verbose output. To force a specific version, use --tlsv1.2 or --tlsv1.3.

Q: What is mutual TLS (mTLS) and how do I use it with curl?

Mutual TLS requires both the server and client to present certificates. Use: curl --cert client.pem --key client-key.pem --cacert server-ca.pem URL. The --cert/--key pair authenticates the client; --cacert verifies the server.

Q: How do I use curl through an HTTP proxy?

Use curl -x http://proxy:port URL. For an HTTPS proxy: curl -x https://proxy:port URL. Alternatively, set the http_proxy and https_proxy environment variables — curl picks them up automatically.

Q: How do I use curl with a SOCKS5 proxy?

Use curl --socks5 host:port URL for local DNS resolution, or curl --socks5-hostname host:port URL to resolve DNS through the proxy (important for privacy/Tor). Example with SSH tunnel: ssh -D 1080 user@bastion, then curl --socks5 localhost:1080 URL.

Q: How do I authenticate with a proxy server in curl?

Use curl -x http://proxy:port -U user:password URL. The -U (or --proxy-user) flag sends credentials to the proxy. This is separate from -u, which authenticates with the target server.

Q: How do I exclude certain hosts from the proxy in curl?

Use --noproxy "localhost,127.0.0.1,*.internal.com" or set the NO_PROXY environment variable. Supports wildcards (*.example.com). Use --noproxy "*" to bypass the proxy entirely for a single request.

Q: How do I test HTTPS on localhost with curl?

For quick testing: curl -k https://localhost:8443/. For proper validation: curl --resolve myapp.local:443:127.0.0.1 --cacert local-ca.pem https://myapp.local/. The --resolve approach lets the certificate hostname match correctly.

Q: How do I override DNS resolution for a specific host in curl?

Use curl --resolve host:port:IP URL. Example: curl --resolve api.example.com:443:192.168.1.100 https://api.example.com/. This bypasses DNS for that host:port pair only — no need to edit /etc/hosts.

Configuring HTTPS certificates, TLS versions, proxies, and custom DNS resolution in curl is essential for secure API communication, CI/CD pipelines, and debugging network issues. This guide covers every SSL, TLS, proxy, and network flag — from disabling certificate checks with -k for local development to setting up mutual TLS with --cert and routing traffic through SOCKS5 proxies. Each option includes a clear explanation, security considerations, and a ready-to-copy example.

SSL & Proxy Flags Quick Reference

Flag	Category	Description
-k	SSL/TLS	Allow insecure connections — skip all SSL verification
--cacert	SSL/TLS	Verify the server certificate against a specific CA bundle
--cert	SSL/TLS	Provide a client certificate for mutual TLS authentication
--key	SSL/TLS	Provide the private key file for the client certificate
--tlsv1.2	SSL/TLS	Use TLS version 1.2 or higher for the connection
--tlsv1.3	SSL/TLS	Use TLS version 1.3 or higher for the connection
--ssl-reqd	SSL/TLS	Require SSL/TLS for the connection (fail if not available)
--ciphers	SSL/TLS	Specify which SSL ciphers to use for the connection
--cert-type	SSL/TLS	Specify the client certificate type (PEM, DER, ENG, P12)
--pinnedpubkey	SSL/TLS	Pin and verify the server public key (HPKP-style)
-x	Proxy	Route all traffic through the specified proxy server
--socks5	Proxy	Route the connection through a SOCKS5 proxy
--proxy-user	Proxy	Provide username:password for the proxy server
--noproxy	Proxy	List of hosts that should not go through the proxy
--socks5-hostname	Proxy	SOCKS5 proxy with DNS resolution through the proxy
--proxy-cacert	Proxy	CA certificate to verify the HTTPS proxy itself
--resolve	Network	Map a specific host:port pair to a custom IP address
--connect-to	Network	Connect to a different host:port than the URL specifies
--local-port	Network	Set the local port number or range for the connection
--interface	Network	Bind the connection to a specific network interface
--dns-servers	Network	Use custom DNS servers instead of system defaults (c-ares)

-kSSL/TLS

Allow insecure connections — skip all SSL verification

--cacertSSL/TLS

Verify the server certificate against a specific CA bundle

--certSSL/TLS

Provide a client certificate for mutual TLS authentication

--keySSL/TLS

Provide the private key file for the client certificate

--tlsv1.2SSL/TLS

Use TLS version 1.2 or higher for the connection

--tlsv1.3SSL/TLS

Use TLS version 1.3 or higher for the connection

--ssl-reqdSSL/TLS

Require SSL/TLS for the connection (fail if not available)

--ciphersSSL/TLS

Specify which SSL ciphers to use for the connection

--cert-typeSSL/TLS

Specify the client certificate type (PEM, DER, ENG, P12)

--pinnedpubkeySSL/TLS

Pin and verify the server public key (HPKP-style)

-xProxy

Route all traffic through the specified proxy server

--socks5Proxy

Route the connection through a SOCKS5 proxy

--proxy-userProxy

Provide username:password for the proxy server

--noproxyProxy

List of hosts that should not go through the proxy

--socks5-hostnameProxy

SOCKS5 proxy with DNS resolution through the proxy

--proxy-cacertProxy

CA certificate to verify the HTTPS proxy itself

--resolveNetwork

Map a specific host:port pair to a custom IP address

--connect-toNetwork

Connect to a different host:port than the URL specifies

--local-portNetwork

Set the local port number or range for the connection

--interfaceNetwork

Bind the connection to a specific network interface

--dns-serversNetwork

Use custom DNS servers instead of system defaults (c-ares)

curl -k: Ignore SSL Certificate Errors

What it does: The -k (or --insecure) flag disables all SSL/TLS certificate verification. curl will not check if the server certificate is signed by a trusted CA, if the hostname matches, or if the certificate has expired.
When to use: Use only for local development with self-signed certificates or testing environments. For staging/production, use --cacert with the actual CA certificate instead — it is both safer and more explicit.

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

Never use -k in production scripts or CI/CD pipelines. It disables all certificate validation, making your connection vulnerable to man-in-the-middle attacks. Use --cacert to trust a specific CA instead.

curl --cacert: Use a Custom CA Certificate

What it does: The --cacert flag tells curl to verify the server's SSL certificate against a specific CA (Certificate Authority) bundle file in PEM format, instead of the system's default trust store.
When to use: Use when your server uses a certificate signed by a private or internal CA that is not in the system trust store. This is common in corporate environments, Kubernetes clusters, and Docker setups with internal PKI.

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

curl --cert: Client Certificate (Mutual TLS)

What it does: The --cert flag provides a client-side certificate for mutual TLS (mTLS). In mTLS, both the server and the client present certificates to verify each other's identity. The certificate file should be in PEM or PKCS#12 format.
When to use: Required when the server demands client certificate authentication — common in banking APIs, government services, IoT device communication, and zero-trust architectures. Always pair with --key unless the key is embedded in the cert file.

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

curl --key: Client Certificate Private Key

What it does: The --key flag specifies the private key file that pairs with the client certificate provided by --cert. The key must match the certificate. If the key is password-protected, curl will prompt for the passphrase (or use --pass).
When to use: Always use together with --cert. If the private key is already embedded in the certificate file (common with PKCS#12 / .p12 files), you can omit --key.

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

curl --tlsv1.2: Force TLS 1.2 Minimum

What it does: The --tlsv1.2 flag forces curl to use TLS 1.2 as the minimum acceptable version for the SSL/TLS handshake. Older protocols (TLS 1.0, 1.1, SSLv3) are rejected.
When to use: Use to enforce a minimum security standard. TLS 1.2 is required for PCI-DSS compliance and is supported by all modern servers. Most modern curl builds default to TLS 1.2+ already, but this flag makes it explicit.

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

curl --tlsv1.3: Force TLS 1.3 Minimum

What it does: The --tlsv1.3 flag forces curl to use TLS 1.3 — the fastest and most secure TLS version. TLS 1.3 eliminates the extra round-trip in the handshake (0-RTT support) and removes all obsolete cipher suites.
When to use: Use when you know the server supports TLS 1.3 and you want the best performance and security. Note: TLS 1.3 requires OpenSSL 1.1.1+ or a compatible TLS library. Not all servers support it yet.

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

Additional SSL/TLS Options

Flag	Description
--ssl-reqd	Require SSL/TLS for the connection (fail if not available)
--ciphers	Specify which SSL ciphers to use for the connection
--cert-type	Specify the client certificate type (PEM, DER, ENG, P12)
--pinnedpubkey	Pin and verify the server public key (HPKP-style)

--ssl-reqd

Require SSL/TLS for the connection (fail if not available)

--ciphers

Specify which SSL ciphers to use for the connection

--cert-type

Specify the client certificate type (PEM, DER, ENG, P12)

--pinnedpubkey

Pin and verify the server public key (HPKP-style)

curl -x: Use an HTTP/HTTPS Proxy

What it does: The -x (or --proxy) flag routes all curl traffic through the specified proxy server. The format is [protocol://]host[:port]. Supported proxy protocols: HTTP, HTTPS, SOCKS4, SOCKS5.
When to use: Use for corporate proxy servers, debugging with tools like Fiddler, Charles, or mitmproxy, testing geographic restrictions, or when direct internet access is not available. You can also set the http_proxy / https_proxy environment variables instead.

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

curl --socks5: Use a SOCKS5 Proxy

What it does: The --socks5 flag tells curl to use a SOCKS5 proxy for the TCP connection. Unlike HTTP proxies, SOCKS5 operates at the TCP level and can handle any protocol — not just HTTP. DNS resolution is done locally by default; use --socks5-hostname to resolve DNS through the proxy.
When to use: Use for SSH tunnels (ssh -D), Tor network access, or when the proxy must handle non-HTTP protocols. SOCKS5 supports UDP and can optionally handle DNS — making it more flexible than HTTP proxies.

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

curl --proxy-user: Proxy Authentication

What it does: The --proxy-user (or -U) flag sends authentication credentials to the proxy server. The format is user:password. This is separate from server authentication (-u).
When to use: Required when the proxy server demands authentication — common in corporate and enterprise network environments. The credentials are sent to the proxy, not to the target server.

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

curl --noproxy: Bypass Proxy for Specific Hosts

What it does: The --noproxy flag specifies a comma-separated list of hosts, domains, or IP addresses that should bypass the proxy and connect directly. Supports wildcards: *.example.com matches all subdomains.
When to use: Use to exclude localhost, internal services, or specific domains from proxying. This is important when a proxy is set globally via environment variables but some hosts (like local services) need direct access. Use * to bypass the proxy for all hosts.

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

Additional Proxy Options

Flag	Description
--socks5-hostname	SOCKS5 proxy with DNS resolution through the proxy
--proxy-cacert	CA certificate to verify the HTTPS proxy itself

--socks5-hostname

SOCKS5 proxy with DNS resolution through the proxy

--proxy-cacert

CA certificate to verify the HTTPS proxy itself

curl --resolve: Custom DNS Resolution

What it does: The --resolve flag provides a custom IP address for a specific host:port pair, completely bypassing DNS lookup. The format is host:port:address. Multiple --resolve entries can be provided.
When to use: Essential for testing before DNS propagation, verifying a specific backend behind a load balancer, or local development where you need a real hostname for SSL certificate validation. Unlike editing /etc/hosts, this is per-request and port-specific.

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

curl --connect-to: Redirect Connection to Different Host

What it does: The --connect-to flag redirects the TCP connection to a different host:port pair while keeping the original URL for the HTTP request (including the Host header and SNI). Format: HOST1:PORT1:HOST2:PORT2.
When to use: Use to test a specific backend server behind a load balancer without modifying DNS or /etc/hosts. Unlike --resolve, this maps host:port to host:port (not to an IP), which is useful when the target also has a hostname.

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

Additional Network Options

Flag	Description
--local-port	Set the local port number or range for the connection
--interface	Bind the connection to a specific network interface
--dns-servers	Use custom DNS servers instead of system defaults (c-ares)

--local-port

Set the local port number or range for the connection

--interface

Bind the connection to a specific network interface

--dns-servers

Use custom DNS servers instead of system defaults (c-ares)

Real-World SSL & Proxy Scenarios

These examples combine multiple flags to handle common security and networking tasks in development, CI/CD, and production environments.

Testing HTTPS on Localhost

When developing locally with a self-signed certificate, combine --resolve with --cacert (or -k for quick testing). This lets you use a real hostname for proper SSL/SNI without modifying your hosts file.

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

Mutual TLS (Client Certificate Authentication)

Some APIs require both server and client to present certificates. Provide --cert, --key, and --cacert to establish a fully verified two-way TLS connection.

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

Corporate Proxy with Authentication

In corporate networks with mandatory proxy servers, combine -x with -U for proxy credentials. Add --noproxy to exclude internal services from proxying.

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

Docker Container with Internal CA

When services in Docker use certificates from an internal CA, mount the CA certificate into the container and reference it with --cacert. This is safer than -k because it still validates the certificate chain.

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

SOCKS5 Proxy via SSH Tunnel

Create a SOCKS5 proxy with ssh -D and route curl traffic through it using --socks5. This is useful for accessing internal services through a bastion host.

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

Frequently Asked Questions about curl SSL & Proxy

How do I skip SSL certificate verification in curl?

Use curl -k URL or curl --insecure URL. This disables all certificate checks — expiration, hostname mismatch, untrusted CA. Use only for local development. For production, use --cacert with the actual CA certificate.

How do I make curl trust a self-signed certificate?

Use curl --cacert /path/to/ca.pem URL to specify the CA certificate that signed your self-signed cert. This is safer than -k because it still validates the certificate chain — only trusting your specific CA.

How do I check which TLS version curl is using?

Run curl -v URL and look for the line * SSL connection using TLSv1.x / CipherSuite in the verbose output. To force a specific version, use --tlsv1.2 or --tlsv1.3.

What is mutual TLS (mTLS) and how do I use it with curl?

Mutual TLS requires both the server and client to present certificates. Use: curl --cert client.pem --key client-key.pem --cacert server-ca.pem URL. The --cert/--key pair authenticates the client; --cacert verifies the server.

How do I use curl through an HTTP proxy?

Use curl -x http://proxy:port URL. For an HTTPS proxy: curl -x https://proxy:port URL. Alternatively, set the http_proxy and https_proxy environment variables — curl picks them up automatically.

How do I use curl with a SOCKS5 proxy?

Use curl --socks5 host:port URL for local DNS resolution, or curl --socks5-hostname host:port URL to resolve DNS through the proxy (important for privacy/Tor). Example with SSH tunnel: ssh -D 1080 user@bastion, then curl --socks5 localhost:1080 URL.

How do I authenticate with a proxy server in curl?

Use curl -x http://proxy:port -U user:password URL. The -U (or --proxy-user) flag sends credentials to the proxy. This is separate from -u, which authenticates with the target server.

How do I exclude certain hosts from the proxy in curl?

Use --noproxy "localhost,127.0.0.1,*.internal.com" or set the NO_PROXY environment variable. Supports wildcards (*.example.com). Use --noproxy "*" to bypass the proxy entirely for a single request.

How do I test HTTPS on localhost with curl?

For quick testing: curl -k https://localhost:8443/. For proper validation: curl --resolve myapp.local:443:127.0.0.1 --cacert local-ca.pem https://myapp.local/. The --resolve approach lets the certificate hostname match correctly.

How do I override DNS resolution for a specific host in curl?

Use curl --resolve host:port:IP URL. Example: curl --resolve api.example.com:443:192.168.1.100 https://api.example.com/. This bypasses DNS for that host:port pair only — no need to edit /etc/hosts.

How do I fix 'SSL certificate problem: certificate has expired' in curl?

The server certificate has expired. Solutions: (1) Renew the certificate on the server, (2) Update your CA bundle: curl --cacert /path/to/updated-ca.pem URL, (3) For testing only: curl -k URL. Check expiry: curl -v URL 2>&1 | grep expire.

Is it safe to use curl --insecure (-k) in production?

No. The -k flag disables all certificate validation — expiration, hostname, and trust chain. This makes your connection vulnerable to man-in-the-middle attacks. Always use --cacert with the specific CA certificate in production and CI/CD pipelines.