Artifactspublic-v0

curl

master
ply4 git calls152 ms289 KiB2 cachedprotocol v2
174 lines5.4 KiBRaw

NAME

curl_easy_ssls_export - export SSL sessions

SYNOPSIS

c
#include <curl/curl.h>

typedef CURLcode curl_ssls_export_function(CURL *handle,
                                           void *userptr,
                                           const char *session_key,
                                           const unsigned char *shmac,
                                           size_t shmac_len,
                                           const unsigned char *sdata,
                                           size_t sdata_len,
                                           curl_off_t valid_until,
                                           int ietf_tls_id,
                                           const char *alpn,
                                           size_t earlydata_max);

CURLcode curl_easy_ssls_export(CURL *handle,
                               curl_ssls_export_function *export_fn,
                               void *userptr);

DESCRIPTION

This function iterates over all SSL session tickets that belong to the easy handle and invokes the export_fn callback on each of them, as long as the callback returns CURLE_OK.

The callback may then store this information and use curl_easy_ssls_import(3) in another libcurl instance to add SSL session tickets again. Reuse of SSL session tickets may result in faster handshakes and some connections might be able to send request data in the initial packets (0-RTT).

From all the parameters passed to the export_fn only two need to be persisted: either session_key or shamc and always sdata. All other parameters are informative, e.g. allow the callback to act only on specific session tickets.

Note that SSL sessions that involve a client certificate are not exported.

Export Function Parameter

Session Key

This is a printable, null-terminated string that starts with hostname:port the session ticket is originating from and also contains all relevant SSL parameters used in the connection. The key also carries the name and version number of the TLS backend used.

It is recommended to only persist session_key when it can be protected from outside access. Since the hostname appears in plain text, it would allow any third party to see how curl has been used for.

Salted Hash

A binary blob of shmac_len bytes that contains a random salt and a cryptographic hash of the salt and session_key. The salt is generated for every session individually. Storing shmac is recommended when placing session tickets in a file, for example.

A third party may brute-force known hostnames, but cannot "grep" for them.

Session Data

A binary blob of sdata_len bytes, sdata contains all relevant SSL session ticket information for a later import - apart from session_key and shmac.

valid_until

Seconds since EPOCH (1970-01-01) until the session ticket is considered valid.

TLS Version

The IETF assigned number for the TLS version the session ticket originates from. This is 0x0304 for TLSv1.3, 0x0303 for 1.2, etc. Session tickets from version 1.3 have better security properties, so an export might store only those.

ALPN

The ALPN protocol that had been negotiated with the host. This may be NULL if negotiation gave no result or had not been attempted.

Early Data

The maximum amount of bytes the server supports to receive in early data (0-RTT). This is 0 unless the server explicitly indicates support.

%PROTOCOLS%

EXAMPLE

c
static CURLcode my_export_cb(CURL *handle,
                             void *userptr,
                             const char *session_key,
                             const unsigned char *shmac,
                             size_t shmac_len,
                             const unsigned char *sdata,
                             size_t sdata_len,
                             curl_off_t valid_until,
                             int ietf_tls_id,
                             const char *alpn,
                             size_t earlydata_max)
{
  /* persist sdata */
  return CURLE_OK;
}

int main(void)
{
  CURLSHcode sh;
  CURLSH *share = curl_share_init();
  CURLcode result;
  CURL *curl;

  sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);
  if(sh)
    printf("Error: %s\n", curl_share_strerror(sh));

  curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_SHARE, share);

    /* run a transfer, all TLS sessions received are added to the share. */
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
    curl_easy_perform(curl);

    /* export the TLS sessions collected in the share */
    result = curl_easy_ssls_export(curl, my_export_cb, NULL);

    /* always cleanup */
    curl_easy_cleanup(curl);
  }
  curl_share_cleanup(share);
}

%AVAILABILITY%

RETURN VALUE

This function returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3) there can be an error message stored in the error buffer when non-zero is returned.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_easy_ssls_export
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_SHARE (3)
9 - curl_share_setopt (3)
10 - curl_easy_ssls_import (3)
11Protocol:
12 - TLS
13TLS-backend:
14 - GnuTLS
15 - OpenSSL
16 - wolfSSL
17 - mbedTLS
18Added-in: 8.12.0
19---
21# NAME
23curl_easy_ssls_export - export SSL sessions
25# SYNOPSIS
27~~~c
28#include <curl/curl.h>
30typedef CURLcode curl_ssls_export_function(CURL *handle,
31 void *userptr,
32 const char *session_key,
33 const unsigned char *shmac,
34 size_t shmac_len,
35 const unsigned char *sdata,
36 size_t sdata_len,
37 curl_off_t valid_until,
38 int ietf_tls_id,
39 const char *alpn,
40 size_t earlydata_max);
42CURLcode curl_easy_ssls_export(CURL *handle,
43 curl_ssls_export_function *export_fn,
44 void *userptr);
45~~~
47# DESCRIPTION
49This function iterates over all SSL session tickets that belong to the
50easy handle and invokes the **export_fn** callback on each of them, as
51long as the callback returns **CURLE_OK**.
53The callback may then store this information and use curl_easy_ssls_import(3)
54in another libcurl instance to add SSL session tickets again. Reuse of
55SSL session tickets may result in faster handshakes and some connections
56might be able to send request data in the initial packets (0-RTT).
58From all the parameters passed to the **export_fn** only two need to be
59persisted: either **session_key** or **shamc** and always **sdata**. All
60other parameters are informative, e.g. allow the callback to act only
61on specific session tickets.
63Note that SSL sessions that involve a client certificate are not exported.
65# Export Function Parameter
67## Session Key
69This is a printable, null-terminated string that starts with **hostname:port**
70the session ticket is originating from and also contains all relevant SSL
71parameters used in the connection. The key also carries the name and version
72number of the TLS backend used.
74It is recommended to only persist **session_key** when it can be protected
75from outside access. Since the hostname appears in plain text, it would
76allow any third party to see how curl has been used for.
78## Salted Hash
80A binary blob of **shmac_len** bytes that contains a random salt and
81a cryptographic hash of the salt and **session_key**. The salt is generated
82for every session individually. Storing **shmac** is recommended when
83placing session tickets in a file, for example.
85A third party may brute-force known hostnames, but cannot "grep" for them.
87## Session Data
89A binary blob of **sdata_len** bytes, **sdata** contains all relevant
90SSL session ticket information for a later import - apart from **session_key**
91and **shmac**.
93## valid_until
95Seconds since EPOCH (1970-01-01) until the session ticket is considered
96valid.
98## TLS Version
100The IETF assigned number for the TLS version the session ticket originates
101from. This is **0x0304** for TLSv1.3, **0x0303** for 1.2, etc. Session
102tickets from version 1.3 have better security properties, so an export
103might store only those.
105## ALPN
107The ALPN protocol that had been negotiated with the host. This may be
108**NULL** if negotiation gave no result or had not been attempted.
110## Early Data
112The maximum amount of bytes the server supports to receive in early data
113(0-RTT). This is 0 unless the server explicitly indicates support.
115# %PROTOCOLS%
117# EXAMPLE
119~~~c
120static CURLcode my_export_cb(CURL *handle,
121 void *userptr,
122 const char *session_key,
123 const unsigned char *shmac,
124 size_t shmac_len,
125 const unsigned char *sdata,
126 size_t sdata_len,
127 curl_off_t valid_until,
128 int ietf_tls_id,
129 const char *alpn,
130 size_t earlydata_max)
132 /* persist sdata */
133 return CURLE_OK;
136int main(void)
138 CURLSHcode sh;
139 CURLSH *share = curl_share_init();
140 CURLcode result;
141 CURL *curl;
143 sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);
144 if(sh)
145 printf("Error: %s\n", curl_share_strerror(sh));
147 curl = curl_easy_init();
148 if(curl) {
149 curl_easy_setopt(curl, CURLOPT_SHARE, share);
151 /* run a transfer, all TLS sessions received are added to the share. */
152 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
153 curl_easy_perform(curl);
155 /* export the TLS sessions collected in the share */
156 result = curl_easy_ssls_export(curl, my_export_cb, NULL);
158 /* always cleanup */
159 curl_easy_cleanup(curl);
160 }
161 curl_share_cleanup(share);
163~~~
165# %AVAILABILITY%
167# RETURN VALUE
169This function returns a CURLcode indicating success or error.
171CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
172libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
173there can be an error message stored in the error buffer when non-zero is
174returned.
Diagnostics4 git calls · 152 ms
CallStatusSizeTime0152 ms
discover200152 B3 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 · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
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=147
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.2 KiB147 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2274
git.response.cache=MISS
git.response.duration_ms=147
git.fetch.wants=ce0363acea3ed61bc7da0fa432e9a58fb0ab46fb
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=2274
git.pkt.payload.max=2253
git.sideband.band1.bytes=2252
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
a5e32e1049278821
Request
12a04b0d…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format