curl_easy_ssls_export(3) Library Functions Manual curl_easy_ssls_export(3)
NAME
curl_easy_ssls_export - export SSL sessions
SYNOPSIS
#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 or SRP
username/password are not exported.
Export Function Parameter
Session Key
This is a printable, 0-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 just
"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
This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS,
POP3S, SMTPS etc.
This option works only with the following TLS backends: BearSSL,
GnuTLS, OpenSSL, mbedTLS and wolfSSL
EXAMPLE
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 rc;
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);
rc = curl_easy_ssls_export(curl, my_export_cb, NULL);
/* always cleanup */
curl_easy_cleanup(curl);
}
curl_share_cleanup(share);
}
AVAILABILITY
Added in curl 8.12.0
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.
SEE ALSO
CURLOPT_SHARE(3), curl_easy_ssls_import(3), curl_share_setopt(3)
libcurl 2025-02-08 curl_easy_ssls_export(3)
curl 8.12.0 - Generated Wed Feb 19 16:44:34 CST 2025