Artifactspublic-v0

curl

master
ply4 git calls412 ms290 KiB2 cachedprotocol v2
196 lines6.7 KiBRaw

NAME

CURLOPT_SSL_CTX_FUNCTION - SSL context callback

SYNOPSIS

c
#include <curl/curl.h>

CURLcode ssl_ctx_callback(CURL *curl, void *ssl_ctx, void *clientp);

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION,
                          ssl_ctx_callback);

DESCRIPTION

Pass a pointer to your callback function, which should match the prototype shown above.

This callback function gets called by libcurl immediately before the initialization of an SSL connection after having processed all other SSL related options to give a last chance to an application to modify the behavior of the SSL initialization. The ssl_ctx parameter is a pointer to the SSL library's SSL_CTX for OpenSSL or wolfSSL, a pointer to mbedtls_ssl_config for mbedTLS. If an error is returned from the callback no attempt to establish a connection is made and the perform operation returns the callback's error code. Set the clientp argument passed in to this callback with the CURLOPT_SSL_CTX_DATA(3) option.

This function gets called for all new connections made to a server, during the SSL negotiation. While ssl_ctx points to a newly initialized object each time, the pointer may still be the same as in a prior call.

To use this callback, a non-trivial amount of knowledge of your SSL library is necessary. For example, you can use this function to call library-specific callbacks to add additional validation code for certificates, and even to change the actual URI of an HTTPS request.

For OpenSSL, asynchronous certificate verification via SSL_set_retry_verify is supported. When SSL_set_retry_verify is set, the transfer is paused. When verification should continue, call curl_easy_pause(3) to unpause the transfer. (Added in 8.3.0, Pausing added in 8.16.0)

The CURLOPT_SSL_CTX_FUNCTION(3) callback allows the application to reach in and modify SSL details in the connection without libcurl itself knowing anything about it, which then subsequently can lead to libcurl unknowingly reusing SSL connections with different properties. To remedy this you may set CURLOPT_FORBID_REUSE(3) from the callback function.

Note that this callback is not only invoked for a connection to the transfer's URL, but also for DoH requests or redirects (if configured) or if happy eyeballing is done, for example performing HTTP/2 and/or HTTP/3 connects in parallel.

Connections that are set up with this callback can be put in the connection pool by libcurl and then reused in following transfers without the callback being called. The connections may even be selected from the pool to be used for transfers not using this callback. If the callback should only be valid for the specific transfer the callback verifies, it should be marked unsuitable for reuse with CURLOPT_FORBID_REUSE(3).

We strongly discourage setting a client certificate with this option, or any other sensitive data. The application must prevent both connection and TLS session reuse when these settings should not outlive the transfer. In addition to setting CURLOPT_FORBID_REUSE(3), set CURLOPT_SSL_SESSIONID_CACHE(3) to 0 because a new connection can resume a session established with these settings even though the callback is invoked again.

If you are using DNS-over-HTTPS (DoH) via CURLOPT_DOH_URL(3) then this callback is also called for those transfers and the curl handle is set to an internal handle. This behavior is subject to change. We recommend setting CURLOPT_PRIVATE(3) on your curl handle so you can identify it correctly in the context callback. If you have a reason to modify DoH SSL context please let us know on the curl-library mailing list because we are considering removing this capability.

libcurl does not guarantee the lifetime of the passed in object once this callback function has returned. Your application must not assume that it can keep using the SSL context or data derived from it once this function is completed.

For libcurl builds using TLS backends that support CA caching and CURLOPT_CA_CACHE_TIMEOUT(3) is not set to zero, multiple calls to this callback may be done with the same CA store in memory.

DEFAULT

NULL

%PROTOCOLS%

EXAMPLE

c
/* OpenSSL specific */

#include <openssl/ssl.h>
#include <curl/curl.h>
#include <stdio.h>

static CURLcode sslctx_function(CURL *curl, void *sslctx, void *pointer)
{
  X509_STORE *store;
  X509 *cert = NULL;
  BIO *bio;
  char *mypem = pointer;
  /* get a BIO */
  bio = BIO_new_mem_buf(mypem, -1);
  /* use it to read the PEM formatted certificate from memory into an
   * X509 structure that SSL can use
   */
  PEM_read_bio_X509(bio, &cert, 0, NULL);
  if(!cert)
    printf("PEM_read_bio_X509 failed...\n");

  /* get a pointer to the X509 certificate store (which may be empty) */
  store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx);

  /* add our certificate to this store */
  if(X509_STORE_add_cert(store, cert) == 0)
    printf("error adding certificate\n");

  /* decrease reference counts */
  X509_free(cert);
  BIO_free(bio);

  /* all set to go */
  return CURLE_OK;
}

int main(void)
{
  CURL *curl;
  CURLcode result;
  /* CA cert in PEM format, replace the XXXs */
  const char *mypem =
    "-----BEGIN CERTIFICATE-----\n"
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
    "-----END CERTIFICATE-----\n";

  curl_global_init(CURL_GLOBAL_ALL);
  curl = curl_easy_init();

  curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM");
  curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
  curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");

  curl_easy_setopt(curl, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function);
  curl_easy_setopt(curl, CURLOPT_SSL_CTX_DATA, mypem);
  result = curl_easy_perform(curl);
  if(result == CURLE_OK)
    printf("*** transfer succeeded ***\n");
  else
    printf("*** transfer failed ***\n");

  curl_easy_cleanup(curl);
  curl_global_cleanup();
  return (int)result;
}

%AVAILABILITY%

RETURN VALUE

CURLE_OK if supported; or an error such as:

CURLE_NOT_BUILT_IN - Not supported by the SSL backend

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_SSL_CTX_FUNCTION
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_CA_CACHE_TIMEOUT (3)
9 - CURLOPT_CAINFO (3)
10 - CURLOPT_CAINFO_BLOB (3)
11 - CURLOPT_SSL_CTX_DATA (3)
12 - CURLOPT_SSL_VERIFYHOST (3)
13 - CURLOPT_SSL_VERIFYPEER (3)
14Protocol:
15 - TLS
16TLS-backend:
17 - OpenSSL
18 - wolfSSL
19 - mbedTLS
20Added-in: 7.10.6
21---
23# NAME
25CURLOPT_SSL_CTX_FUNCTION - SSL context callback
27# SYNOPSIS
29~~~c
30#include <curl/curl.h>
32CURLcode ssl_ctx_callback(CURL *curl, void *ssl_ctx, void *clientp);
34CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION,
35 ssl_ctx_callback);
36~~~
38# DESCRIPTION
40Pass a pointer to your callback function, which should match the prototype
41shown above.
43This callback function gets called by libcurl immediately before the
44initialization of an SSL connection after having processed all other SSL
45related options to give a last chance to an application to modify the behavior
46of the SSL initialization. The *ssl_ctx* parameter is a pointer to the SSL
47library's *SSL_CTX* for OpenSSL or wolfSSL, a pointer to *mbedtls_ssl_config*
48for mbedTLS. If an error is returned from the callback no attempt to establish
49a connection is made and the perform operation returns the callback's error
50code. Set the *clientp* argument passed in to this callback with the
51CURLOPT_SSL_CTX_DATA(3) option.
53This function gets called for all new connections made to a server, during the
54SSL negotiation. While *ssl_ctx* points to a newly initialized object each
55time, the pointer may still be the same as in a prior call.
57To use this callback, a non-trivial amount of knowledge of your SSL library is
58necessary. For example, you can use this function to call library-specific
59callbacks to add additional validation code for certificates, and even to
60change the actual URI of an HTTPS request.
62For OpenSSL, asynchronous certificate verification via *SSL_set_retry_verify*
63is supported. When *SSL_set_retry_verify* is set, the transfer is paused.
64When verification should continue, call curl_easy_pause(3) to unpause
65the transfer. (Added in 8.3.0, Pausing added in 8.16.0)
67The CURLOPT_SSL_CTX_FUNCTION(3) callback allows the application to reach in
68and modify SSL details in the connection without libcurl itself knowing
69anything about it, which then subsequently can lead to libcurl unknowingly
70reusing SSL connections with different properties. To remedy this you may set
71CURLOPT_FORBID_REUSE(3) from the callback function.
73Note that this callback is not only invoked for a connection to the transfer's
74URL, but also for DoH requests or redirects (if configured) or if happy
75eyeballing is done, for example performing HTTP/2 and/or HTTP/3 connects in
76parallel.
78Connections that are set up with this callback can be put in the connection
79pool by libcurl and then reused in following transfers without the callback
80being called. The connections may even be selected from the pool to be used for
81transfers not using this callback. If the callback should only be valid for
82the specific transfer the callback verifies, it should be marked unsuitable
83for reuse with CURLOPT_FORBID_REUSE(3).
85We strongly discourage setting a client certificate with this option, or any
86other sensitive data. The application must prevent both connection and TLS
87session reuse when these settings should not outlive the transfer. In addition
88to setting CURLOPT_FORBID_REUSE(3), set CURLOPT_SSL_SESSIONID_CACHE(3) to 0
89because a new connection can resume a session established with these settings
90even though the callback is invoked again.
92If you are using DNS-over-HTTPS (DoH) via CURLOPT_DOH_URL(3) then this
93callback is also called for those transfers and the curl handle is set to an
94internal handle. **This behavior is subject to change.** We recommend setting
95CURLOPT_PRIVATE(3) on your curl handle so you can identify it correctly in the
96context callback. If you have a reason to modify DoH SSL context please let us
97know on the curl-library mailing list because we are considering removing this
98capability.
100libcurl does not guarantee the lifetime of the passed in object once this
101callback function has returned. Your application must not assume that it can
102keep using the SSL context or data derived from it once this function is
103completed.
105For libcurl builds using TLS backends that support CA caching and
106CURLOPT_CA_CACHE_TIMEOUT(3) is not set to zero, multiple calls to this
107callback may be done with the same CA store in memory.
109# DEFAULT
111NULL
113# %PROTOCOLS%
115# EXAMPLE
117~~~c
118/* OpenSSL specific */
120#include <openssl/ssl.h>
121#include <curl/curl.h>
122#include <stdio.h>
124static CURLcode sslctx_function(CURL *curl, void *sslctx, void *pointer)
126 X509_STORE *store;
127 X509 *cert = NULL;
128 BIO *bio;
129 char *mypem = pointer;
130 /* get a BIO */
131 bio = BIO_new_mem_buf(mypem, -1);
132 /* use it to read the PEM formatted certificate from memory into an
133 * X509 structure that SSL can use
134 */
135 PEM_read_bio_X509(bio, &cert, 0, NULL);
136 if(!cert)
137 printf("PEM_read_bio_X509 failed...\n");
139 /* get a pointer to the X509 certificate store (which may be empty) */
140 store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx);
142 /* add our certificate to this store */
143 if(X509_STORE_add_cert(store, cert) == 0)
144 printf("error adding certificate\n");
146 /* decrease reference counts */
147 X509_free(cert);
148 BIO_free(bio);
150 /* all set to go */
151 return CURLE_OK;
154int main(void)
156 CURL *curl;
157 CURLcode result;
158 /* CA cert in PEM format, replace the XXXs */
159 const char *mypem =
160 "-----BEGIN CERTIFICATE-----\n"
161 "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
162 "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
163 "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
164 "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
165 "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
166 "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"
167 "-----END CERTIFICATE-----\n";
169 curl_global_init(CURL_GLOBAL_ALL);
170 curl = curl_easy_init();
172 curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM");
173 curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
174 curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
176 curl_easy_setopt(curl, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function);
177 curl_easy_setopt(curl, CURLOPT_SSL_CTX_DATA, mypem);
178 result = curl_easy_perform(curl);
179 if(result == CURLE_OK)
180 printf("*** transfer succeeded ***\n");
181 else
182 printf("*** transfer failed ***\n");
184 curl_easy_cleanup(curl);
185 curl_global_cleanup();
186 return (int)result;
188~~~
190# %AVAILABILITY%
192# RETURN VALUE
194CURLE_OK if supported; or an error such as:
196CURLE_NOT_BUILT_IN - Not supported by the SSL backend
Diagnostics4 git calls · 412 ms
CallStatusSizeTime0412 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=408
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.9 KiB408 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2970
git.response.cache=MISS
git.response.duration_ms=408
git.fetch.wants=13e84b0ae7a9e022305340ab9985f8a90d566c87
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2970
git.pkt.payload.max=2949
git.sideband.band1.bytes=2948
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e322fc8c5c5aae
Request
a2f500cb…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format