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