source: mod_gnutls/src/gnutls_cache.h @ 764fef3

asyncio
Last change on this file since 764fef3 was 764fef3, checked in by Fiona Klute <fiona.klute@…>, 9 months ago

Load cached proxy TLS sessions from cache

  • Property mode set to 100644
File size: 5.9 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 * Internal cache configuration structure
159 */
160struct mgs_cache {
161    /** Socache provider to use for this cache */
162    const ap_socache_provider_t *prov;
163    /** The actual socache instance */
164    ap_socache_instance_t *socache;
165    /** Cache configuration string (as passed to the socache create
166     * function, for logging) */
167    const char *config;
168    /** Mutex for cache access (used only if the cache type is not
169     * thread-safe) */
170    apr_global_mutex_t *mutex;
171};
172
173/**
174 * Write cache status to a mod_status report
175 *
176 * @param cache the cache to report on
177 *
178 * @param header_title string to prefix the report with to distinguish
179 * caches
180 *
181 * @param r status output is added to the response for this request
182 *
183 * @param flags request flags, used to toggle "short status" mode
184 *
185 * @return request status, currently always `OK`
186 */
187int mgs_cache_status(mgs_cache_t cache, const char *header_title,
188                     request_rec *r, int flags);
189
190#endif /** __MOD_GNUTLS_CACHE_H__ */
Note: See TracBrowser for help on using the repository browser.