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 - BearSSL 17 - wolfSSL 18 - mbedTLS 19Added-in: 8.12.0 20--- 21 22# NAME 23 24curl_easy_ssls_export - export SSL sessions 25 26# SYNOPSIS 27 28~~~c 29#include <curl/curl.h> 30 31typedef CURLcode curl_ssls_export_function(CURL *handle, 32 void *userptr, 33 const char *session_key, 34 const unsigned char *shmac, 35 size_t shmac_len, 36 const unsigned char *sdata, 37 size_t sdata_len, 38 curl_off_t valid_until, 39 int ietf_tls_id, 40 const char *alpn, 41 size_t earlydata_max); 42 43CURLcode curl_easy_ssls_export(CURL *handle, 44 curl_ssls_export_function *export_fn, 45 void *userptr); 46~~~ 47 48# DESCRIPTION 49 50This function iterates over all SSL session tickets that belong to the 51easy handle and invokes the **export_fn** callback on each of them, as 52long as the callback returns **CURLE_OK**. 53 54The callback may then store this information and use curl_easy_ssls_import(3) 55in another libcurl instance to add SSL session tickets again. Reuse of 56SSL session tickets may result in faster handshakes and some connections 57might be able to send request data in the initial packets (0-RTT). 58 59From all the parameters passed to the **export_fn** only two need to be 60persisted: either **session_key** or **shamc** and always **sdata**. All 61other parameters are informative, e.g. allow the callback to act only 62on specific session tickets. 63 64Note that SSL sessions that involve a client certificate or SRP 65username/password are not exported. 66 67# Export Function Parameter 68 69## Session Key 70 71This is a printable, 0-terminated string that starts with **hostname:port** 72the session ticket is originating from and also contains all relevant 73SSL parameters used in the connection. The key also carries the name 74and version number of the TLS backend used. 75 76It is recommended to only persist **session_key** when it can be protected 77from outside access. Since the hostname appears in plain text, it would 78allow any third party to see how curl has been used for. 79 80## Salted Hash 81 82A binary blob of **shmac_len** bytes that contains a random salt and 83a cryptographic hash of the salt and **session_key**. The salt is generated 84for every session individually. Storing **shmac** is recommended when 85placing session tickets in a file, for example. 86 87A third party may brute-force known hostnames, but cannot just "grep" for 88them. 89 90## Session Data 91 92A binary blob of **sdata_len** bytes, **sdata** contains all relevant 93SSL session ticket information for a later import - apart from **session_key** 94and **shmac**. 95 96## valid_until 97 98Seconds since EPOCH (1970-01-01) until the session ticket is considered 99valid. 100 101## TLS Version 102 103The IETF assigned number for the TLS version the session ticket originates 104from. This is **0x0304** for TLSv1.3, **0x0303** for 1.2, etc. Session 105tickets from version 1.3 have better security properties, so an export 106might store only those. 107 108## ALPN 109 110The ALPN protocol that had been negotiated with the host. This may be 111**NULL** if negotiation gave no result or had not been attempted. 112 113## Early Data 114 115The maximum amount of bytes the server supports to receive in early data 116(0-RTT). This is 0 unless the server explicitly indicates support. 117 118# %PROTOCOLS% 119 120# EXAMPLE 121 122~~~c 123CURLcode my_export_cb(CURL *handle, 124 void *userptr, 125 const char *session_key, 126 const unsigned char *shmac, 127 size_t shmac_len, 128 const unsigned char *sdata, 129 size_t sdata_len, 130 curl_off_t valid_until, 131 int ietf_tls_id, 132 const char *alpn, 133 size_t earlydata_max) 134{ 135 /* persist sdata */ 136 return CURLE_OK; 137} 138 139int main(void) 140{ 141 CURLSHcode sh; 142 CURLSH *share = curl_share_init(); 143 CURLcode rc; 144 CURL *curl; 145 146 sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION); 147 if(sh) 148 printf("Error: %s\n", curl_share_strerror(sh)); 149 150 curl = curl_easy_init(); 151 if(curl) { 152 curl_easy_setopt(curl, CURLOPT_SHARE, share); 153 154 rc = curl_easy_ssls_export(curl, my_export_cb, NULL); 155 156 /* always cleanup */ 157 curl_easy_cleanup(curl); 158 } 159 curl_share_cleanup(share); 160} 161~~~ 162 163# %AVAILABILITY% 164 165# RETURN VALUE 166 167This function returns a CURLcode indicating success or error. 168 169CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 170libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3) 171there can be an error message stored in the error buffer when non-zero is 172returned. 173