1 #ifndef HEADER_CURL_VTLS_SCACHE_H 2 #define HEADER_CURL_VTLS_SCACHE_H 3 /*************************************************************************** 4 * _ _ ____ _ 5 * Project ___| | | | _ \| | 6 * / __| | | | |_) | | 7 * | (__| |_| | _ <| |___ 8 * \___|\___/|_| \_\_____| 9 * 10 * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 11 * 12 * This software is licensed as described in the file COPYING, which 13 * you should have received as part of this distribution. The terms 14 * are also available at https://curl.se/docs/copyright.html. 15 * 16 * You may opt to use, copy, modify, merge, publish, distribute and/or sell 17 * copies of the Software, and permit persons to whom the Software is 18 * furnished to do so, under the terms of the COPYING file. 19 * 20 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY 21 * KIND, either express or implied. 22 * 23 * SPDX-License-Identifier: curl 24 * 25 ***************************************************************************/ 26 #include "curl_setup.h" 27 #include "cfilters.h" 28 #include "urldata.h" 29 30 #ifdef USE_SSL 31 32 struct Curl_cfilter; 33 struct Curl_easy; 34 struct Curl_ssl_scache; 35 struct Curl_ssl_session; 36 struct ssl_peer; 37 38 /* RFC 8446 (TLSv1.3) restrict lifetime to one week max, for 39 * other, less secure versions, we restrict it to a day */ 40 #define CURL_SCACHE_MAX_13_LIFETIME_SEC (60*60*24*7) 41 #define CURL_SCACHE_MAX_12_LIFETIME_SEC (60*60*24) 42 43 /* Create a session cache for up to max_peers endpoints with a total 44 * of up to max_sessions SSL sessions per peer */ 45 CURLcode Curl_ssl_scache_create(size_t max_peers, 46 size_t max_sessions_per_peer, 47 struct Curl_ssl_scache **pscache); 48 49 void Curl_ssl_scache_destroy(struct Curl_ssl_scache *scache); 50 51 /* Create a key from peer and TLS configuration information that is 52 * unique for how the connection filter wants to establish a TLS 53 * connection to the peer. 54 * If the filter is a TLS proxy filter, it will use the proxy relevant 55 * information. 56 * @param cf the connection filter wanting to use it 57 * @param peer the peer the filter wants to talk to 58 * @param tls_id identifier of TLS implementation for sessions. Should 59 * include full version if session data from other versions 60 * is to be avoided. 61 * @param ppeer_key on successful return, the key generated 62 */ 63 CURLcode Curl_ssl_peer_key_make(struct Curl_cfilter *cf, 64 const struct ssl_peer *peer, 65 const char *tls_id, 66 char **ppeer_key); 67 68 /* Lock session cache mutex. 69 * Call this before calling other Curl_ssl_*session* functions 70 * Caller should unlock this mutex as soon as possible, as it may block 71 * other SSL connection from making progress. 72 * The purpose of explicitly locking SSL session cache data is to allow 73 * individual SSL engines to manage session lifetime in their specific way. 74 */ 75 void Curl_ssl_scache_lock(struct Curl_easy *data); 76 77 /* Unlock session cache mutex */ 78 void Curl_ssl_scache_unlock(struct Curl_easy *data); 79 80 /* Get TLS session object from the cache for the ssl_peer_ey. 81 * scache mutex must be locked (see Curl_ssl_scache_lock). 82 * Caller must make sure that the ownership of returned session object 83 * is properly taken (e.g. its refcount is incremented 84 * under scache mutex). 85 * @param cf the connection filter wanting to use it 86 * @param data the transfer involved 87 * @param ssl_peer_key the key for lookup 88 * @param sobj on return, the object for the peer key or NULL 89 */ 90 bool Curl_ssl_scache_get_obj(struct Curl_cfilter *cf, 91 struct Curl_easy *data, 92 const char *ssl_peer_key, 93 void **sobj); 94 95 typedef void Curl_ssl_scache_obj_dtor(void *sobj); 96 97 /* Add a TLS session related object to the cache. 98 * Replaces an existing object with the same peer_key. 99 * scache mutex must be locked (see Curl_ssl_scache_lock). 100 * Call takes ownership of `sobj`, using `sobj_dtor_cb` 101 * to deallocate it. Is called in all outcomes, either right away or 102 * later when the session cache is cleaned up. 103 * Caller must ensure that it has properly shared ownership of `sobj` 104 * with cache (e.g. incrementing refcount on success) 105 * @param cf the connection filter wanting to use it 106 * @param data the transfer involved 107 * @param ssl_peer_key the key for lookup 108 * @param sobj the TLS session object 109 * @param sobj_free_cb callback to free the session objectt 110 */ 111 CURLcode Curl_ssl_scache_add_obj(struct Curl_cfilter *cf, 112 struct Curl_easy *data, 113 const char *ssl_peer_key, 114 void *sobj, 115 Curl_ssl_scache_obj_dtor *sobj_dtor_cb); 116 117 /* All about a SSL session ticket */ 118 struct Curl_ssl_session { 119 const unsigned char *sdata; /* session ticket data, plain bytes */ 120 size_t sdata_len; /* number of bytes in sdata */ 121 curl_off_t valid_until; /* seconds since EPOCH until ticket expires */ 122 int ietf_tls_id; /* TLS protocol identifier negotiated */ 123 char *alpn; /* APLN TLS negotiated protocol string */ 124 size_t earlydata_max; /* max 0-RTT data supported by peer */ 125 const unsigned char *quic_tp; /* Optional QUIC transport param bytes */ 126 size_t quic_tp_len; /* number of bytes in quic_tp */ 127 struct Curl_llist_node list; /* internal storage handling */ 128 }; 129 130 /* Create a `session` instance. Does NOT need locking. 131 * Takes ownership of `sdata` and `sobj` regardless of return code. 132 * @param sdata bytes of SSL session data or NULL (sobj then required) 133 * @param sdata_len amount of session data bytes 134 * @param ietf_tls_id IETF protocol version, e.g. 0x304 for TLSv1.3 135 * @param alpn ALPN protocol selected or NULL 136 * @param valid_until seconds since EPOCH when session expires, pass 0 137 * in case this is not known. 138 * @param psession on return the scached session instance created 139 */ 140 CURLcode 141 Curl_ssl_session_create(unsigned char *sdata, size_t sdata_len, 142 int ietf_tls_id, const char *alpn, 143 curl_off_t valid_until, 144 size_t earlydata_max, 145 struct Curl_ssl_session **psession); 146 147 /* Variation of session creation with quic transport parameter bytes, 148 * Takes ownership of `quic_tp` regardless of return code. */ 149 CURLcode 150 Curl_ssl_session_create2(unsigned char *sdata, size_t sdata_len, 151 int ietf_tls_id, const char *alpn, 152 curl_off_t valid_until, 153 size_t earlydata_max, 154 unsigned char *quic_tp, size_t quic_tp_len, 155 struct Curl_ssl_session **psession); 156 157 /* Destroy a `session` instance. Can be called with NULL. 158 * Does NOT need locking. */ 159 void Curl_ssl_session_destroy(struct Curl_ssl_session *s); 160 161 /* Put the scache session into the cache. Does NOT need locking. 162 * Call takes ownership of `s` in all outcomes. 163 * @param cf the connection filter wanting to use it 164 * @param data the transfer involved 165 * @param ssl_peer_key the key for lookup 166 * @param s the scache session object 167 */ 168 CURLcode Curl_ssl_scache_put(struct Curl_cfilter *cf, 169 struct Curl_easy *data, 170 const char *ssl_peer_key, 171 struct Curl_ssl_session *s); 172 173 /* Take a matching scache session from the cache. Does NOT need locking. 174 * @param cf the connection filter wanting to use it 175 * @param data the transfer involved 176 * @param ssl_peer_key the key for lookup 177 * @param s on return, the scache session object or NULL 178 */ 179 CURLcode Curl_ssl_scache_take(struct Curl_cfilter *cf, 180 struct Curl_easy *data, 181 const char *ssl_peer_key, 182 struct Curl_ssl_session **ps); 183 184 /* Return a taken scache session to the cache. Does NOT need locking. 185 * Depending on TLS version and other criteria, it may cache it again 186 * or destroy it. Maybe called with a NULL session. 187 */ 188 void Curl_ssl_scache_return(struct Curl_cfilter *cf, 189 struct Curl_easy *data, 190 const char *ssl_peer_key, 191 struct Curl_ssl_session *s); 192 193 /* Remove all sessions and obj for the peer_key. Does NOT need locking. */ 194 void Curl_ssl_scache_remove_all(struct Curl_cfilter *cf, 195 struct Curl_easy *data, 196 const char *ssl_peer_key); 197 198 #ifdef USE_SSLS_EXPORT 199 200 CURLcode Curl_ssl_session_import(struct Curl_easy *data, 201 const char *ssl_peer_key, 202 const unsigned char *shmac, size_t shmac_len, 203 const unsigned char *sdata, size_t sdata_len); 204 205 CURLcode Curl_ssl_session_export(struct Curl_easy *data, 206 curl_ssls_export_cb *export_fn, 207 void *userptr); 208 209 #endif /* USE_SSLS_EXPORT */ 210 211 #else /* USE_SSL */ 212 213 #define Curl_ssl_scache_create(x,y,z) ((void)x, CURLE_OK) 214 #define Curl_ssl_scache_destroy(x) do {} while(0) 215 216 #endif /* USE_SSL (else) */ 217 218 #endif /* HEADER_CURL_VTLS_SCACHE_H */ 219