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, 0-terminated string	that starts with host-
	      name:port	the session ticket is originating from and  also  con-
	      tains  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  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 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: 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-06-03	      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+14.3.quarterly>

home | help