source: mod_gnutls/src/gnutls_cache.h

mod_gnutls/0.11.0
Last change on this file was 641d11b, checked in by Fiona Klute <fiona.klute@…>, 4 months ago

Delete session tickets for proxy connections when using them

Tickets should not be reused because an attacker could correlate
connections using the same ticket. Cache deletion code has been
extracted from socache_delete_session() into a generic function.

  • Property mode set to 100644
File size: 6.3 KB
Line 
1/*
2 *  Copyright 2004-2005 Paul Querna
3 *  Copyright 2014 Nikos Mavrogiannopoulos
4 *  Copyright 2015-2020 Fiona Klute
5 *
6 *  Licensed under the Apache License, Version 2.0 (the "License");
7 *  you may not use this file except in compliance with the License.
8 *  You may obtain a copy of the License at
9 *
10 *      http://www.apache.org/licenses/LICENSE-2.0
11 *
12 *  Unless required by applicable law or agreed to in writing, software
13 *  distributed under the License is distributed on an "AS IS" BASIS,
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 *  See the License for the specific language governing permissions and
16 *  limitations under the License.
17 */
18
19/**
20 * @file
21 *
22 * Generic object cache for mod_gnutls.
23 */
24
25#ifndef __MOD_GNUTLS_CACHE_H__
26#define __MOD_GNUTLS_CACHE_H__
27
28#include "mod_gnutls.h"
29#include <httpd.h>
30#include <ap_socache.h>
31
32/** Name of the mod_gnutls cache access mutex, for use with Apache's
33 * `Mutex` directive */
34#define MGS_CACHE_MUTEX_NAME "gnutls-cache"
35
36/** 8K is the maximum size accepted when receiving OCSP responses,
37 * sessions cache entries should be much smaller. The buffer is
38 * reallocated to actual size after fetching, so memory waste is
39 * minimal and temporary. */
40#define MGS_SESSION_FETCH_BUF_SIZE (8 * 1024)
41
42/**
43 * Configure a cache instance
44 *
45 * This function is supposed to be called during config and
46 * initializes an mgs_cache_t by finding the named socache provider
47 * and creating a cache instance with the given configuration. Note
48 * that the socache instance is only created, not initialized, which
49 * is supposed to happen during post_config.
50 *
51 * @param cache pointer to the mgs_cache_t, will be assigned only if
52 * configuration succeeds
53 *
54 * @param server associated server for logging purposes
55 *
56 * @param type socache provider type
57 *
58 * @param config configuration string for the socache provider, may be
59 * `NULL` if the provider accepts an empty configuration
60 *
61 * @param pconf configuration memory pool, used to store cache
62 * configuration
63 *
64 * @param ptemp temporary memory pool
65 */
66const char *mgs_cache_inst_config(mgs_cache_t *cache, server_rec *server,
67                                  const char* type, const char* config,
68                                  apr_pool_t *pconf, apr_pool_t *ptemp);
69
70/**
71 * Initialize the internal cache configuration structure. This
72 * function is called after the configuration file(s) have been
73 * parsed.
74 *
75 * @param pconf configuration memory pool
76 * @param ptemp temporary memory pool
77 * @param s default server of the Apache configuration, head of the
78 * server list
79 * @param sc mod_gnutls data associated with `s`
80 */
81int mgs_cache_post_config(apr_pool_t *pconf, apr_pool_t *ptemp,
82                          server_rec *s, mgs_srvconf_rec *sc);
83
84/**
85 * (Re-)Initialize the cache in a child process after forking.
86 *
87 * @param p child memory pool provided by Apache
88 * @param s default server of the Apache configuration, head of the
89 * server list
90 * @param cache the cache to reinit
91 * @param mutex_name name of the mutex associated with the cache for
92 * logging purposes
93 */
94int mgs_cache_child_init(apr_pool_t *p, server_rec *server,
95                         mgs_cache_t cache, const char *mutex_name);
96
97/**
98 * Set up caching for the given TLS session.
99 *
100 * @param ctxt mod_gnutls session context
101 *
102 * @return 0
103 */
104int mgs_cache_session_init(mgs_handle_t *ctxt);
105
106
107
108/**
109 * Convert a `time_t` into a null terminated string in a format
110 * compatible with OpenSSL's `ASN1_TIME_print()`.
111 *
112 * @param t time_t time
113 * @param str Location to store the time string
114 * @param strsize The maximum length that can be stored in `str`
115 *
116 * @return `str`
117 */
118char *mgs_time2sz(time_t t, char *str, int strsize);
119
120/**
121 * Store function for the mod_gnutls object caches.
122 *
123 * @param cache the cache to store the entry in
124 * @param s server associated with the cache entry
125 * @param key key for the cache entry
126 * @param data data to be cached
127 * @param expiry expiration time
128 *
129 * @return `-1` on error, `0` on success
130 */
131int mgs_cache_store(mgs_cache_t cache, server_rec *server, gnutls_datum_t key,
132                    gnutls_datum_t data, apr_time_t expiry);
133
134/**
135 * Fetch function for the mod_gnutls object caches.
136 *
137 * *Warning*: The `data` element of the returned `gnutls_datum_t` is
138 * allocated using `gnutls_malloc()` for compatibility with the GnuTLS
139 * session caching API, and must be released using `gnutls_free()`.
140 *
141 * @param cache the cache to fetch from
142 *
143 * @param server server context for the request
144 *
145 * @param key key for the cache entry to be fetched
146 *
147 * @param output pre-allocated buffer to write to and its size
148 *
149 * @param pool pool to allocate temporary memory from
150 *
151 * @return APR status or error value
152 */
153apr_status_t mgs_cache_fetch(mgs_cache_t cache, server_rec *server,
154                             gnutls_datum_t key, gnutls_datum_t *output,
155                             apr_pool_t *pool);
156
157/**
158 * Delete an item from the mod_gnutls object caches.
159 *
160 * @param cache the cache to delete from
161 *
162 * @param server server context for the request
163 *
164 * @param key key for the cache entry to be deleted
165 *
166 * @param pool pool to allocate temporary memory from
167 *
168 * @return APR status or error value
169 */
170apr_status_t mgs_cache_delete(mgs_cache_t cache, server_rec *server,
171                              gnutls_datum_t key, apr_pool_t *pool);
172
173/**
174 * Internal cache configuration structure
175 */
176struct mgs_cache {
177    /** Socache provider to use for this cache */
178    const ap_socache_provider_t *prov;
179    /** The actual socache instance */
180    ap_socache_instance_t *socache;
181    /** Cache configuration string (as passed to the socache create
182     * function, for logging) */
183    const char *config;
184    /** Mutex for cache access (used only if the cache type is not
185     * thread-safe) */
186    apr_global_mutex_t *mutex;
187};
188
189/**
190 * Write cache status to a mod_status report
191 *
192 * @param cache the cache to report on
193 *
194 * @param header_title string to prefix the report with to distinguish
195 * caches
196 *
197 * @param r status output is added to the response for this request
198 *
199 * @param flags request flags, used to toggle "short status" mode
200 *
201 * @return request status, currently always `OK`
202 */
203int mgs_cache_status(mgs_cache_t cache, const char *header_title,
204                     request_rec *r, int flags);
205
206#endif /** __MOD_GNUTLS_CACHE_H__ */
Note: See TracBrowser for help on using the repository browser.