curl/docs/libcurl/curl_global_sslset.3

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_global_sslset 3 "15 July 2017" "libcurl 7.56" "libcurl Manual"
.SH NAME
curl_global_sslset - Select SSL backend to use with libcurl
.SH SYNOPSIS
.nf
#include <curl/curl.h>

typedef struct {
  curl_sslbackend id;
  const char *name;
} curl_ssl_backend;

typedef enum {
  CURLSSLBACKEND_NONE = 0,
  CURLSSLBACKEND_OPENSSL = 1,
  CURLSSLBACKEND_GNUTLS = 2,
  CURLSSLBACKEND_NSS = 3,
  CURLSSLBACKEND_GSKIT = 5,
  CURLSSLBACKEND_POLARSSL = 6, /* deprecated */
  CURLSSLBACKEND_WOLFSSL = 7,
  CURLSSLBACKEND_SCHANNEL = 8,
  CURLSSLBACKEND_SECURETRANSPORT = 9,
  CURLSSLBACKEND_AXTLS = 10, /* deprecated */
  CURLSSLBACKEND_MBEDTLS = 11,
  CURLSSLBACKEND_MESALINK = 12,
  CURLSSLBACKEND_BEARSSL = 13
} curl_sslbackend;

CURLsslset curl_global_sslset(curl_sslbackend id,
                              const char *name,
                              curl_ssl_backend ***avail);
.fi
.SH DESCRIPTION
This function configures at runtime which SSL backend to use with
libcurl. This function can only be used to select an SSL backend once, and it
must be called \fBbefore\fP \fIcurl_global_init(3)\fP.

The backend can be identified by the \fIid\fP
(e.g. \fBCURLSSLBACKEND_OPENSSL\fP). The backend can also be specified via the
\fIname\fP parameter for a case insensitive match (passing -1 as \fIid\fP). If
both \fIid\fP and \fIname\fP are specified, the \fIname\fP will be ignored.

If neither \fIid\fP nor \fPname\fP are specified, the function will fail with
\fBCURLSSLSET_UNKNOWN_BACKEND\fP and set the \fIavail\fP pointer to the
NULL-terminated list of available backends. The available backends are those
that this particular build of libcurl supports.

Since libcurl 7.60.0, the \fIavail\fP pointer will always be set to the list
of alternatives if non-NULL.

Upon success, the function returns \fBCURLSSLSET_OK\fP.

If the specified SSL backend is not available, the function returns
\fBCURLSSLSET_UNKNOWN_BACKEND\fP and sets the \fIavail\fP pointer to a
NULL-terminated list of available SSL backends. In this case, you may call the
function again to try to select a different backend.

The SSL backend can be set only once. If it has already been set, a subsequent
attempt to change it will result in a \fBCURLSSLSET_TOO_LATE\fP.

This function is thread-safe since libcurl 7.84.0 if
\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
(most platforms).

If this is not thread-safe, you must not call this function when any other
thread in the program (i.e. a thread sharing the same memory) is running.
This does not just mean no other thread that is using libcurl.
.SH EXAMPLE
.nf
  /* choose a specific backend */
  curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL);

  /* list the available ones */
  const curl_ssl_backend **list;
  curl_global_sslset((curl_sslbackend)-1, NULL, &list);

  for(i = 0; list[i]; i++)
    printf("SSL backend #%d: '%s' (ID: %d)\\n",
           i, list[i]->name, list[i]->id);
.fi
.SH AVAILABILITY
This function was added in libcurl 7.56.0. Before this version, there was no
support for choosing SSL backends at runtime.
.SH RETURN VALUE
If this function returns \fICURLSSLSET_OK\fP, the backend was successfully
selected.

If the chosen backend is unknown (or support for the chosen backend has not
been compiled into libcurl), the function returns
\fICURLSSLSET_UNKNOWN_BACKEND\fP.

If the backend had been configured previously, or if \fIcurl_global_init(3)\fP
has already been called, the function returns \fICURLSSLSET_TOO_LATE\fP.

If this libcurl was built completely without SSL support, with no backends at
all, this function returns \fICURLSSLSET_NO_BACKENDS\fP.
.SH "SEE ALSO"
.BR curl_global_init "(3), "
.BR libcurl "(3) "