Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
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_im-
       port(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  pa-
       rameters	 are  informative, e.g.	allow the callback to act only on spe-
       cific session tickets.

       Note that SSL sessions that involve a client certificate	or  SRP	 user-
       name/password 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  rec-
	      ommended 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 prop-
	      erties, 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 at-
	      tempted.

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

PROTOCOLS
       This functionality affects all TLS based	protocols: HTTPS, FTPS,	IMAPS,
       POP3S, SMTPS etc.

       This  option  works  only  with	the  following	TLS  backends: 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 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	will be	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
       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				  2026-06-11	      curl_easy_ssls_export(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=curl_easy_ssls_export&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help