quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

curl_global_sslset.md (4296B)

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