#ifndef HEADER_CURL_VTLS_SCACHE_H #define HEADER_CURL_VTLS_SCACHE_H /*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * * Copyright (C) Daniel Stenberg, , et al. * * This software is licensed as described in the file COPYING, which * you should have received as part of this distribution. The terms * are also available at https://curl.se/docs/copyright.html. * * You may opt to use, copy, modify, merge, publish, distribute and/or sell * copies of the Software, and permit persons to whom the Software is * furnished to do so, under the terms of the COPYING file. * * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY * KIND, either express or implied. * * SPDX-License-Identifier: curl * ***************************************************************************/ #include "curl_setup.h" #include "cfilters.h" #include "urldata.h" #ifdef USE_SSL struct Curl_cfilter; struct Curl_easy; struct Curl_ssl_scache; struct Curl_ssl_session; struct ssl_peer; /* RFC 8446 (TLSv1.3) restrict lifetime to one week max, for * other, less secure versions, we restrict it to a day */ #define CURL_SCACHE_MAX_13_LIFETIME_SEC (60*60*24*7) #define CURL_SCACHE_MAX_12_LIFETIME_SEC (60*60*24) /* Create a session cache for up to max_peers endpoints with a total * of up to max_sessions SSL sessions per peer */ CURLcode Curl_ssl_scache_create(size_t max_peers, size_t max_sessions_per_peer, struct Curl_ssl_scache **pscache); void Curl_ssl_scache_destroy(struct Curl_ssl_scache *scache); /* Create a key from peer and TLS configuration information that is * unique for how the connection filter wants to establish a TLS * connection to the peer. * If the filter is a TLS proxy filter, it will use the proxy relevant * information. * @param cf the connection filter wanting to use it * @param peer the peer the filter wants to talk to * @param tls_id identifier of TLS implementation for sessions. Should * include full version if session data from other versions * is to be avoided. * @param ppeer_key on successful return, the key generated */ CURLcode Curl_ssl_peer_key_make(struct Curl_cfilter *cf, const struct ssl_peer *peer, const char *tls_id, char **ppeer_key); /* Lock session cache mutex. * Call this before calling other Curl_ssl_*session* functions * Caller should unlock this mutex as soon as possible, as it may block * other SSL connection from making progress. * The purpose of explicitly locking SSL session cache data is to allow * individual SSL engines to manage session lifetime in their specific way. */ void Curl_ssl_scache_lock(struct Curl_easy *data); /* Unlock session cache mutex */ void Curl_ssl_scache_unlock(struct Curl_easy *data); /* Get TLS session object from the cache for the ssl_peer_ey. * scache mutex must be locked (see Curl_ssl_scache_lock). * Caller must make sure that the ownership of returned session object * is properly taken (e.g. its refcount is incremented * under scache mutex). * @param cf the connection filter wanting to use it * @param data the transfer involved * @param ssl_peer_key the key for lookup * @param sobj on return, the object for the peer key or NULL */ bool Curl_ssl_scache_get_obj(struct Curl_cfilter *cf, struct Curl_easy *data, const char *ssl_peer_key, void **sobj); typedef void Curl_ssl_scache_obj_dtor(void *sobj); /* Add a TLS session related object to the cache. * Replaces an existing object with the same peer_key. * scache mutex must be locked (see Curl_ssl_scache_lock). * Call takes ownership of `sobj`, using `sobj_dtor_cb` * to deallocate it. Is called in all outcomes, either right away or * later when the session cache is cleaned up. * Caller must ensure that it has properly shared ownership of `sobj` * with cache (e.g. incrementing refcount on success) * @param cf the connection filter wanting to use it * @param data the transfer involved * @param ssl_peer_key the key for lookup * @param sobj the TLS session object * @param sobj_free_cb callback to free the session objectt */ CURLcode Curl_ssl_scache_add_obj(struct Curl_cfilter *cf, struct Curl_easy *data, const char *ssl_peer_key, void *sobj, Curl_ssl_scache_obj_dtor *sobj_dtor_cb); /* All about a SSL session ticket */ struct Curl_ssl_session { const unsigned char *sdata; /* session ticket data, plain bytes */ size_t sdata_len; /* number of bytes in sdata */ curl_off_t time_received; /* seconds since EPOCH ticket was received */ int lifetime_secs; /* ticket lifetime (-1 unknown) */ int ietf_tls_id; /* TLS protocol identifier negotiated */ char *alpn; /* APLN TLS negotiated protocol string */ struct Curl_llist_node list; /* internal storage handling */ }; /* Create a `session` instance. Does NOT need locking. * Takes ownership of `sdata` and `sobj` regardless of return code. * @param sdata bytes of SSL session data or NULL (sobj then required) * @param sdata_len amount of session data bytes * @param ietf_tls_id IETF protocol version, e.g. 0x304 for TLSv1.3 * @param alpn ALPN protocol selected or NULL * @param time_received seconds since EPOCH session was received, pass 0 * to have the value set to time of call * @param lifetime_secs seconds of announced lifetime, <0 if unknown. * values longer than 1 week will be capped as * required by RFC 8446 * @param psession on return the scached session instance created */ CURLcode Curl_ssl_session_create(unsigned char *sdata, size_t sdata_len, int ietf_tls_id, const char *alpn, curl_off_t time_received, long lifetime_secs, struct Curl_ssl_session **psession); /* Destroy a `session` instance. Can be called with NULL. * Does NOT need locking. */ void Curl_ssl_session_destroy(struct Curl_ssl_session *s); /* Put the scache session into the cache. Does NOT need locking. * Call takes ownership of `s` in all outcomes. * @param cf the connection filter wanting to use it * @param data the transfer involved * @param ssl_peer_key the key for lookup * @param s the scache session object */ CURLcode Curl_ssl_scache_put(struct Curl_cfilter *cf, struct Curl_easy *data, const char *ssl_peer_key, struct Curl_ssl_session *s); /* Take a matching scache session from the cache. Does NOT need locking. * @param cf the connection filter wanting to use it * @param data the transfer involved * @param ssl_peer_key the key for lookup * @param s on return, the scache session object or NULL */ CURLcode Curl_ssl_scache_take(struct Curl_cfilter *cf, struct Curl_easy *data, const char *ssl_peer_key, struct Curl_ssl_session **ps); /* Return a taken scache session to the cache. Does NOT need locking. * Depending on TLS version and other criteria, it may cache it again * or destroy it. Maybe called with a NULL session. */ void Curl_ssl_scache_return(struct Curl_cfilter *cf, struct Curl_easy *data, const char *ssl_peer_key, struct Curl_ssl_session *s); /* Remove all sessions and obj for the peer_key. Does NOT need locking. */ void Curl_ssl_scache_remove_all(struct Curl_cfilter *cf, struct Curl_easy *data, const char *ssl_peer_key); #else /* USE_SSL */ #define Curl_ssl_scache_create(x,y) CURLE_OK #define Curl_ssl_scache_destroy(x) CURLE_OK #endif /* USE_SSL (else) */ #endif /* HEADER_CURL_VTLS_SCACHE_H */