1CURLOPT_SSL_CTX_FUNCTION(3)curl_easy_setopt optionsCURLOPT_SSL_CTX_FUNCTION(3)
2
3
4

NAME

6       CURLOPT_SSL_CTX_FUNCTION - SSL context callback for OpenSSL, wolfSSL or
7       mbedTLS
8

SYNOPSIS

10       #include <curl/curl.h>
11
12       CURLcode ssl_ctx_callback(CURL *curl, void *ssl_ctx, void *clientp);
13
14       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION,
15                                 ssl_ctx_callback);
16

DESCRIPTION

18       This option only works for libcurl powered by OpenSSL, wolfSSL, mbedTLS
19       or BearSSL. If libcurl was built against another SSL library this func‐
20       tionality is absent.
21
22       Pass a pointer to your callback function, which should match the proto‐
23       type shown above.
24
25       This  callback function gets called by libcurl just before the initial‐
26       ization of an SSL connection after having processed all other  SSL  re‐
27       lated options to give a last chance to an application to modify the be‐
28       havior of the SSL initialization. The ssl_ctx parameter is  actually  a
29       pointer  to the SSL library's SSL_CTX for OpenSSL or wolfSSL, a pointer
30       to mbedtls_ssl_config for mbedTLS or a pointer to br_ssl_client_context
31       for  BearSSL.  If  an error is returned from the callback no attempt to
32       establish a connection is made and the perform  operation  will  return
33       the  callback's  error  code.  Set  the  clientp argument with the CUR‐
34       LOPT_SSL_CTX_DATA(3) option.
35
36       This function will get called on all new connections made to a  server,
37       during  the SSL negotiation. The ssl_ctx will point to a newly initial‐
38       ized object each time, but note the pointer may be the same as  from  a
39       prior call.
40
41       To use this properly, a non-trivial amount of knowledge of your SSL li‐
42       brary is necessary. For example, you can use this function to call  li‐
43       brary-specific callbacks to add additional validation code for certifi‐
44       cates, and even to change the actual URI of an HTTPS request.
45
46       WARNING: The CURLOPT_SSL_CTX_FUNCTION(3) callback allows  the  applica‐
47       tion  to  reach  in  and  modify  SSL details in the connection without
48       libcurl itself knowing anything about it, which then  subsequently  can
49       lead  to  libcurl  unknowingly  reusing  SSL connections with different
50       properties. To remedy this you may set CURLOPT_FORBID_REUSE(3) from the
51       callback function.
52
53       WARNING:  If  you are using DNS-over-HTTPS (DoH) via CURLOPT_DOH_URL(3)
54       then this callback will also be called for those transfers and the curl
55       handle  is  set  to  an  internal  handle.  This behavior is subject to
56       change. We recommend before performing your transfer  set  CURLOPT_PRI‐
57       VATE(3) on your curl handle so you can identify it in the context call‐
58       back. If you have a reason to modify DoH SSL context please let us know
59       on  the  curl-library  mailing list because we are considering removing
60       this capability.
61

DEFAULT

63       NULL
64

PROTOCOLS

66       All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
67

EXAMPLE

69       /* OpenSSL specific */
70
71       #include <openssl/ssl.h>
72       #include <curl/curl.h>
73       #include <stdio.h>
74
75       static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm)
76       {
77         X509_STORE *store;
78         X509 *cert = NULL;
79         BIO *bio;
80         char *mypem = parm;
81         /* get a BIO */
82         bio = BIO_new_mem_buf(mypem, -1);
83         /* use it to read the PEM formatted certificate from memory into an
84          * X509 structure that SSL can use
85          */
86         PEM_read_bio_X509(bio, &cert, 0, NULL);
87         if(cert == NULL)
88           printf("PEM_read_bio_X509 failed...\n");
89
90         /* get a pointer to the X509 certificate store (which may be empty) */
91         store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx);
92
93         /* add our certificate to this store */
94         if(X509_STORE_add_cert(store, cert) == 0)
95           printf("error adding certificate\n");
96
97         /* decrease reference counts */
98         X509_free(cert);
99         BIO_free(bio);
100
101         /* all set to go */
102         return CURLE_OK;
103       }
104
105       int main(void)
106       {
107         CURL * ch;
108         CURLcode rv;
109         char *mypem = /* example CA cert PEM - shortened */
110           "-----BEGIN CERTIFICATE-----\n"
111           "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\n"
112           "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\n"
113           "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\n"
114           "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\n"
115           "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\n"
116           "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\n"
117           "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\n"
118           "-----END CERTIFICATE-----\n";
119
120         curl_global_init(CURL_GLOBAL_ALL);
121         ch = curl_easy_init();
122
123         curl_easy_setopt(ch, CURLOPT_SSLCERTTYPE, "PEM");
124         curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L);
125         curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/");
126
127         /* Retrieve page using cacerts' certificate -> will succeed
128          * load the certificate by installing a function doing the necessary
129          * "modifications" to the SSL CONTEXT just before link init
130          */
131         curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function);
132         curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem);
133         rv = curl_easy_perform(ch);
134         if(!rv)
135           printf("*** transfer succeeded ***\n");
136         else
137           printf("*** transfer failed ***\n");
138
139         curl_easy_cleanup(ch);
140         curl_global_cleanup();
141         return rv;
142       }
143

AVAILABILITY

145       Added in 7.11.0 for OpenSSL, in  7.42.0  for  wolfSSL,  in  7.54.0  for
146       mbedTLS, in 7.83.0 in BearSSL. Other SSL backends are not supported.
147

RETURN VALUE

149       CURLE_OK if supported; or an error such as:
150
151       CURLE_NOT_BUILT_IN - Not supported by the SSL backend
152
153       CURLE_UNKNOWN_OPTION
154

SEE ALSO

156       CURLOPT_SSL_CTX_DATA(3), CURLOPT_SSL_VERIFYPEER(3),
157
158
159
160libcurl 8.0.1                  February 07, 2023   CURLOPT_SSL_CTX_FUNCTION(3)
Impressum