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