xref: /curl/docs/libcurl/curl_global_sslset.md (revision 5a488251) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_global_sslset
5Section: 3
6Source: libcurl
7See-also:
8  - curl_global_init (3)
9  - libcurl (3)
10Protocol:
11  - All
12Added-in: 7.56.0
13---
14
15# NAME
16
17curl_global_sslset - select SSL backend to use
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24CURLsslset curl_global_sslset(curl_sslbackend id,
25                              const char *name,
26                              const curl_ssl_backend ***avail);
27~~~
28
29# DESCRIPTION
30
31This function configures at runtime which SSL backend to use with
32libcurl. This function can only be used to select an SSL backend once, and it
33must be called **before** curl_global_init(3).
34
35The backend can be identified by the *id*
36(e.g. **CURLSSLBACKEND_OPENSSL**). The backend can also be specified via the
37*name* parameter for a case insensitive match (passing
38**CURLSSLBACKEND_NONE** as *id*). If both *id* and *name* are
39specified, the *name* is ignored.
40
41If neither *id* nor *name* are specified, the function fails with
42**CURLSSLSET_UNKNOWN_BACKEND** and set the *avail* pointer to the
43NULL-terminated list of available backends. The available backends are those
44that this particular build of libcurl supports.
45
46Since libcurl 7.60.0, the *avail* pointer is always set to the list of
47alternatives if non-NULL.
48
49Upon success, the function returns **CURLSSLSET_OK**.
50
51If the specified SSL backend is not available, the function returns
52**CURLSSLSET_UNKNOWN_BACKEND** and sets the *avail* pointer to a
53NULL-terminated list of available SSL backends. In this case, you may call the
54function again to try to select a different backend.
55
56The SSL backend can be set only once. If it has already been set, a subsequent
57attempt to change it results in a **CURLSSLSET_TOO_LATE** getting returned.
58
59This function is thread-safe since libcurl 7.84.0 if
60curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set
61(most platforms).
62
63If this is not thread-safe, you must not call this function when any other
64thread in the program (i.e. a thread sharing the same memory) is running.
65This does not just mean no other thread that is using libcurl.
66
67# OpenSSL
68
69The name "OpenSSL" is used for all versions of OpenSSL and its associated
70forks/flavors in this function. OpenSSL, BoringSSL, LibreSSL, quictls and
71AmiSSL are all supported by libcurl, but in the eyes of
72curl_global_sslset(3) they are all just "OpenSSL". They all mostly
73provide the same API.
74
75curl_version_info(3) can return more specific info about the exact
76OpenSSL flavor and version number is use.
77
78# struct
79
80~~~c
81typedef struct {
82  curl_sslbackend id;
83  const char *name;
84} curl_ssl_backend;
85
86typedef enum {
87  CURLSSLBACKEND_NONE = 0,
88  CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */
89  CURLSSLBACKEND_GNUTLS = 2,
90  CURLSSLBACKEND_NSS = 3,
91  CURLSSLBACKEND_GSKIT = 5, /* deprecated */
92  CURLSSLBACKEND_POLARSSL = 6, /* deprecated */
93  CURLSSLBACKEND_WOLFSSL = 7,
94  CURLSSLBACKEND_SCHANNEL = 8,
95  CURLSSLBACKEND_SECURETRANSPORT = 9,
96  CURLSSLBACKEND_AXTLS = 10, /* deprecated */
97  CURLSSLBACKEND_MBEDTLS = 11,
98  CURLSSLBACKEND_MESALINK = 12, /* deprecated */
99  CURLSSLBACKEND_BEARSSL = 13,
100  CURLSSLBACKEND_RUSTLS = 14
101} curl_sslbackend;
102~~~
103
104# %PROTOCOLS%
105
106# EXAMPLE
107
108~~~c
109int main(void)
110{
111  int i;
112  /* choose a specific backend */
113  curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL);
114
115  /* list the available ones */
116  const curl_ssl_backend **list;
117  curl_global_sslset(CURLSSLBACKEND_NONE, NULL, &list);
118
119  for(i = 0; list[i]; i++)
120    printf("SSL backend #%d: '%s' (ID: %d)\n",
121           i, list[i]->name, list[i]->id);
122}
123~~~
124
125# %AVAILABILITY%
126
127# RETURN VALUE
128
129If this function returns *CURLSSLSET_OK*, the backend was successfully
130selected.
131
132If the chosen backend is unknown (or support for the chosen backend has not
133been compiled into libcurl), the function returns
134*CURLSSLSET_UNKNOWN_BACKEND*.
135
136If the backend had been configured previously, or if curl_global_init(3)
137has already been called, the function returns *CURLSSLSET_TOO_LATE*.
138
139If this libcurl was built completely without SSL support, with no backends at
140all, this function returns *CURLSSLSET_NO_BACKENDS*.
141