libcurl TLS options
At the time of writing this, there are no less than forty different options for curl_easy_setopt that are dedicated for controlling how libcurl does SSL and TLS.
Transfers done using TLS use safe defaults but since curl is used in many different scenarios and setups, chances are you will end up in situations where you want to change those behaviors.
CURLOPT_SSLVERSION' andCURLOPT_PROXY_SSLVERSION`you can specify which
SSL or TLS protocol range that is acceptable to you. Traditionally SSL and TLS
protocol versions have been found detect and unsuitable for use over time and
even if curl itself will raise its default lower version over time you might
want to opt for only using the latest and most security protocol versions.
These options take a lowest acceptiable version and optionally a maximum. If the server cannot negotiate a connection with that condition, the transfer will fail.
curl_easy_setopt(easy, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);
Protocol details and behavior
You can select what ciphers to use by setting
You can ask to enable SSL "False Start" with
there are a few other behavior changes to tweak using
A TLS-using client needs to verify that the server it speaks to is the correct and trusted one. This is done by verifying that the server's certificate is signed by a Certificate Authority (CA) for which curl has a public key for and that the certificate contains the server's name. Failing any of these checks will cause the transfer to fail.
For development purposes and for experimenting, curl allows an application to switch off either or both of these checks for the server or for a HTTPS proxy.
CURLOPT_SSL_VERIFYPEERcontrols the check that the certificate is signed by a trusted CA.
CURLOPT_SSL_VERIFYHOSTcontrols the check for the name within the certificate.
CURLOPT_PROXY_SSL_VERIFYPEERis the proxy version of
CURLOPT_PROXY_SSL_VERIFYHOSTis the proxy version of
Optionally, you can tell curl to verify the certificate's public key against a
known hash using
Here too, a mismatch will cause the transfer to fail.
TLS Client certificates
When using TLS and the server asks the client to authentice using
certificates, you typically specify the private key and the corresponding
client certificate using
CURLOPT_SSLCERT. The password
for the key is usually also required to be set, with
Again, the same set of options exist separately for connections to HTTPS
TLS connections offer a (rarely used) feature called Secure Remote
Passwords. Using this, you authenticate the connection for the server using a
name and password and the options are called
For protocols that are using the STARTLS method to upgrade the connection to
TLS (FTP, IMAP, POP3, and SMTP), you usually tell curl to use the non-TLS
version of the protocol when specifying a URL and then ask curl to enable TLS
This option allows a client to let curl continue if it cannot upgrade to TLS, but that's not a recommend path to walk as then you might be using an insecure protocol without properly noticing.
/* require use of SSL for this, or fail */ curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_ALL);