1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_USE_SSL
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_PROXY_SSLVERSION (3)
9  - CURLOPT_SSLVERSION (3)
10  - CURLOPT_SSL_OPTIONS (3)
11---
12
13# NAME
14
15CURLOPT_USE_SSL - request using SSL / TLS for the transfer
16
17# SYNOPSIS
18
19~~~c
20#include <curl/curl.h>
21
22CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USE_SSL, long level);
23~~~
24
25# DESCRIPTION
26
27Pass a long using one of the values from below, to make libcurl use your
28desired *level* of SSL for the transfer.
29
30These are all protocols that start out plain text and get "upgraded" to SSL
31using the STARTTLS command.
32
33This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc.
34
35## CURLUSESSL_NONE
36
37do not attempt to use SSL.
38
39## CURLUSESSL_TRY
40
41Try using SSL, proceed as normal otherwise. Note that server may close the
42connection if the negotiation does not succeed.
43
44## CURLUSESSL_CONTROL
45
46Require SSL for the control connection or fail with *CURLE_USE_SSL_FAILED*.
47
48## CURLUSESSL_ALL
49
50Require SSL for all communication or fail with *CURLE_USE_SSL_FAILED*.
51
52# DEFAULT
53
54CURLUSESSL_NONE
55
56# PROTOCOLS
57
58FTP, SMTP, POP3, IMAP, LDAP
59
60# EXAMPLE
61
62~~~c
63int main(void)
64{
65  CURL *curl = curl_easy_init();
66  if(curl) {
67    curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/file.ext");
68
69    /* require use of SSL for this, or fail */
70    curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
71
72    /* Perform the request */
73    curl_easy_perform(curl);
74  }
75}
76~~~
77
78# AVAILABILITY
79
80Added in 7.11.0. This option was known as CURLOPT_FTP_SSL up to 7.16.4, and
81the constants were known as CURLFTPSSL_*
82Handled by LDAP since 7.81.0. Fully supported by the OpenLDAP backend only.
83
84# RETURN VALUE
85
86Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
87