From 1328f69d53f2f2e937696ea954c480412b018451 Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Fri, 7 Jul 2017 11:49:08 +0200 Subject: vtls: introduce curl_global_sslset() Let's add a compile time safe API to select an SSL backend. This function needs to be called *before* curl_global_init(), and can be called only once. Side note: we do not explicitly test that it is called before curl_global_init(), but we do verify that it is not called multiple times (even implicitly). If SSL is used before the function was called, it will use whatever the CURL_SSL_BACKEND environment variable says (or default to the first available SSL backend), and if a subsequent call to curl_global_sslset() disagrees with the previous choice, it will fail with CURLSSLSET_TOO_LATE. The function also accepts an "avail" parameter to point to a (read-only) NULL-terminated list of available backends. This comes in real handy if an application wants to let the user choose between whatever SSL backends the currently available libcurl has to offer: simply call curl_global_sslset(-1, NULL, &avail); which will return CURLSSLSET_UNKNOWN_BACKEND and populate the avail variable to point to the relevant information to present to the user. Just like with the HTTP/2 push functions, we have to add the function declaration of curl_global_sslset() function to the header file *multi.h* because VMS and OS/400 require a stable order of functions declared in include/curl/*.h (where the header files are sorted alphabetically). This looks a bit funny, but it cannot be helped. Signed-off-by: Johannes Schindelin --- include/curl/curl.h | 5 ----- include/curl/multi.h | 44 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 5 deletions(-) (limited to 'include') diff --git a/include/curl/curl.h b/include/curl/curl.h index 146044398..3936d1e43 100644 --- a/include/curl/curl.h +++ b/include/curl/curl.h @@ -2540,11 +2540,6 @@ CURL_EXTERN CURLcode curl_easy_pause(CURL *handle, int bitmask); #define CURLPAUSE_ALL (CURLPAUSE_RECV|CURLPAUSE_SEND) #define CURLPAUSE_CONT (CURLPAUSE_RECV_CONT|CURLPAUSE_SEND_CONT) -typedef struct { - curl_sslbackend id; - const char *name; -} curl_ssl_backend; - #ifdef __cplusplus } #endif diff --git a/include/curl/multi.h b/include/curl/multi.h index f93e511be..c7c048a05 100644 --- a/include/curl/multi.h +++ b/include/curl/multi.h @@ -432,6 +432,50 @@ typedef int (*curl_push_callback)(CURL *parent, struct curl_pushheaders *headers, void *userp); +/* + * NAME curl_global_sslset() + * + * DESCRIPTION + * + * When built with multiple SSL backends, curl_global_sslset() allows to + * choose one. This function can only be called once, and it must be called + * *before* curl_global_init(). + * + * The backend can be identified by the id (e.g. CURLSSLBACKEND_OPENSSL). The + * backend can also be specified via the name parameter (passing -1 as id). + * If both id and name are specified, the name will be ignored. If neither id + * nor name are specified, the function will fail with + * CURLSSLSET_UNKNOWN_BACKEND and set the "avail" pointer to the + * NULL-terminated list of available backends. + * + * Upon success, the function returns CURLSSLSET_OK. + * + * If the specified SSL backend is not available, the function returns + * CURLSSLSET_UNKNOWN_BACKEND and sets the "avail" pointer to a NULL-terminated + * list of available SSL backends. + * + * The SSL backend can be set only once. If it has already been set, a + * subsequent attempt to change it will result in a CURLSSLSET_TOO_LATE. + */ + +typedef struct { + curl_sslbackend id; + const char *name; +} curl_ssl_backend; + +typedef enum { + CURLSSLSET_OK = 0, + CURLSSLSET_UNKNOWN_BACKEND, + CURLSSLSET_TOO_LATE +} CURLsslset; + +CURL_EXTERN CURLsslset curl_global_sslset(curl_sslbackend id, const char *name, + const curl_ssl_backend ***avail); + +#ifdef __cplusplus +} +#endif + #ifdef __cplusplus } /* end of extern "C" */ #endif -- cgit v1.2.1