curl_global_sslset(3)

1curl_global_sslset(3)               libcurl              curl_global_sslset(3)
2
3
4

NAME

6       curl_global_sslset - Select SSL backend to use with libcurl
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       typedef struct {
12         curl_sslbackend id;
13         const char *name;
14       } curl_ssl_backend;
15
16       typedef enum {
17         CURLSSLBACKEND_NONE = 0,
18         CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */
19         CURLSSLBACKEND_GNUTLS = 2,
20         CURLSSLBACKEND_NSS = 3,
21         CURLSSLBACKEND_GSKIT = 5,
22         CURLSSLBACKEND_POLARSSL = 6, /* deprecated */
23         CURLSSLBACKEND_WOLFSSL = 7,
24         CURLSSLBACKEND_SCHANNEL = 8,
25         CURLSSLBACKEND_SECURETRANSPORT = 9,
26         CURLSSLBACKEND_AXTLS = 10, /* deprecated */
27         CURLSSLBACKEND_MBEDTLS = 11,
28         CURLSSLBACKEND_MESALINK = 12, /* deprecated */
29         CURLSSLBACKEND_BEARSSL = 13,
30         CURLSSLBACKEND_RUSTLS = 14
31       } curl_sslbackend;
32
33       CURLsslset curl_global_sslset(curl_sslbackend id,
34                                     const char *name,
35                                     curl_ssl_backend ***avail);
36

DESCRIPTION

38       This  function  configures  at  runtime  which  SSL backend to use with
39       libcurl. This function can only be used to select an SSL backend  once,
40       and it must be called before [22mcurl_global_init(3).
41
42       The  backend can be identified by the id (e.g. CURLSSLBACKEND_OPENSSL).
43       The backend can also be specified via the name parameter for a case in‐
44       sensitive  match (passing -1 as id). If both id and name are specified,
45       the name will be ignored.
46
47       If neither id nor name are  specified,  the  function  will  fail  with
48       CURLSSLSET_UNKNOWN_BACKEND and set the avail pointer to the NULL-termi‐
49       nated list of available backends. The available backends are those that
50       this particular build of libcurl supports.
51
52       Since  libcurl 7.60.0, the avail pointer will always be set to the list
53       of alternatives if non-NULL.
54
55       Upon success, the function returns CURLSSLSET_OK.
56
57       If the specified SSL backend is not  available,  the  function  returns
58       CURLSSLSET_UNKNOWN_BACKEND  and sets the avail pointer to a NULL-termi‐
59       nated list of available SSL backends. In this case, you  may  call  the
60       function again to try to select a different backend.
61
62       The  SSL  backend  can  be set only once. If it has already been set, a
63       subsequent attempt to change it will result in a CURLSSLSET_TOO_LATE.
64
65       This  function  is  thread-safe  since  libcurl  7.84.0  if   curl_ver‐
66       sion_info(3)  has  the  CURL_VERSION_THREADSAFE  feature  bit set (most
67       platforms).
68
69       If this is not thread-safe, you must not call this  function  when  any
70       other  thread in the program (i.e. a thread sharing the same memory) is
71       running.  This does not  just  mean  no  other  thread  that  is  using
72       libcurl.
73

OpenSSL

75       The  name "OpenSSL" is used for all versions of OpenSSL and its associ‐
76       ated forks/flavors in  this  function.  OpenSSL,  BoringSSL,  libressl,
77       quictls  and  AmiSSL  are  all supported by libcurl, but in the eyes of
78       curl_global_sslset(3) they are all just "OpenSSL". They all mostly pro‐
79       vide the same API.
80
81       curl_version_info(3)  can  return  more  specific  info about the exact
82       OpenSSL flavor and version number is use.
83

EXAMPLE

85         /* choose a specific backend */
86         curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL);
87
88         /* list the available ones */
89         const curl_ssl_backend **list;
90         curl_global_sslset((curl_sslbackend)-1, NULL, &list);
91
92         for(i = 0; list[i]; i++)
93           printf("SSL backend #%d: '%s' (ID: %d)\n",
94                  i, list[i]->name, list[i]->id);
95

AVAILABILITY

97       This function was added in libcurl 7.56.0. Before this  version,  there
98       was no support for choosing SSL backends at runtime.
99

RETURN VALUE

101       If  this  function  returns CURLSSLSET_OK, the backend was successfully
102       selected.
103
104       If the chosen backend is unknown (or support for the chosen backend has
105       not  been  compiled  into libcurl), the function returns CURLSSLSET_UN‐
106       KNOWN_BACKEND.
107
108       If   the   backend   had   been   configured    previously,    or    if
109       curl_global_init(3)  has  already  been  called,  the  function returns
110       CURLSSLSET_TOO_LATE.
111
112       If this libcurl was built completely without SSL support, with no back‐
113       ends at all, this function returns CURLSSLSET_NO_BACKENDS.
114