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