ssl_scache_shmcb.c revision 2d4180e0520fbba07aed22d25dd1e9fce4935d94
/* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/* _ _
* _ __ ___ ___ __| | ___ ___| | mod_ssl
* | '_ ` _ \ / _ \ / _` | / __/ __| | Apache Interface to OpenSSL
* | | | | | | (_) | (_| | \__ \__ \ |
* |_| |_| |_|\___/ \__,_|___|___/___/_|
* |_____|
* Session Cache via Shared Memory (Cyclic Buffer Variant)
*/
#include "ssl_private.h"
/*
* This shared memory based SSL session cache implementation was
* originally written by Geoff Thorpe <geoff geoffthorpe.net> for C2Net
* Europe as a contribution to Ralf Engelschall's mod_ssl project.
*
* Since rewritten by GT to not use alignment-fudging memcpys and reduce
* complexity.
*/
/*
* Header structure - the start of the shared-mem segment
*/
typedef struct {
/* Stats for cache operations */
unsigned long stat_stores;
unsigned long stat_expiries;
unsigned long stat_scrolled;
unsigned long stat_retrieves_hit;
unsigned long stat_retrieves_miss;
unsigned long stat_removes_hit;
unsigned long stat_removes_miss;
/* Number of subcaches */
unsigned int subcache_num;
/* How many indexes each subcache's queue has */
unsigned int index_num;
/* How large each subcache is, including the queue and data */
unsigned int subcache_size;
/* How far into each subcache the data area is (optimisation) */
unsigned int subcache_data_offset;
/* How large the data area in each subcache is (optimisation) */
unsigned int subcache_data_size;
} SHMCBHeader;
/*
* Subcache structure - the start of each subcache, followed by
* indexes then data
*/
typedef struct {
/* The start position and length of the cyclic buffer of indexes */
/* Same for the data area */
/*
* Index structure - each subcache has an array of these
*/
typedef struct {
/* absolute time this entry expires */
/* location within the subcache's data area */
unsigned int data_pos;
/* size (most logic ignores this, we keep it only to minimise memcpy) */
unsigned int data_used;
/* length of the used data which contains the id */
unsigned int id_len;
/* Used to mark explicitly-removed sessions */
unsigned char removed;
} SHMCBIndex;
/* The SHM data segment is of fixed size and stores data as follows.
*
* [ SHMCBHeader | Subcaches ]
*
* The SHMCBHeader header structure stores metadata concerning the
* cache and the contained subcaches.
*
* Subcaches is a hash table of header->subcache_num SHMCBSubcache
* structures. The hash table is indexed by SHMCB_MASK(id). Each
* SHMCBSubcache structure has a fixed size (header->subcache_size),
* which is determined at creation time, and looks like the following:
*
* [ SHMCBSubcache | Indexes | Data ]
*
* Each subcache is prefixed by the SHMCBSubcache structure.
*
* The subcache's "Data" segment is a single cyclic data buffer, of
* total size header->subcache_data_size; data inside is referenced
* using byte offsets. The offset marking the beginning of the cyclic
* buffer is subcache->data_pos the buffer's length is
* subcache->data_used.
*
* "Indexes" is an array of header->index_num SHMCBIndex structures,
* which is used as a cyclic queue; subcache->idx_pos gives the array
* index of the first in use, subcache->idx_used gives the number in
* use. Both ->idx_* values have a range of [0, header->index_num)
*
* Each in-use SHMCBIndex structure represents a single SSL session.
* The ID and data segment are stored consecutively in the subcache's
* cyclic data buffer. The "Data" segment can thus be seen to
* look like this, for example
*
* offset: [ 0 1 2 3 4 5 6 ...
* contents:[ ID1 Data1 ID2 Data2 ID3 ...
*
* where the corresponding indices would look like:
*
* idx1 = { data_pos = 0, data_used = 3, id_len = 1, ...}
* idx2 = { data_pos = 3, data_used = 3, id_len = 1, ...}
* ...
*/
/* This macro takes a pointer to the header and a zero-based index and returns
* a pointer to the corresponding subcache. */
(SHMCBSubcache *)(((unsigned char *)(pHeader)) + \
sizeof(SHMCBHeader) + \
/* This macro takes a pointer to the header and a session id and returns a
* pointer to the corresponding subcache. */
/* This macro takes the same params as the last, generating two outputs for use
* in ap_log_error(...). */
/* This macro takes a pointer to a subcache and a zero-based index and returns
* a pointer to the corresponding SHMCBIndex. */
((SHMCBIndex *)(((unsigned char *)pSubcache) + \
sizeof(SHMCBSubcache)) + num)
/* This macro takes a pointer to the header and a subcache and returns a
* pointer to the corresponding data area. */
/*
* Cyclic functions - assists in "wrap-around"/modulo logic
*/
/* Addition modulo 'mod' */
/* Subtraction (or "distance between") modulo 'mod' */
/* A "normal-to-cyclic" memcpy. */
unsigned int dest_offset, unsigned char *src,
unsigned int src_len)
{
/* It be copied all in one go */
else {
/* Copy the two splits */
}
}
/* A "cyclic-to-normal" memcpy. */
unsigned char *data, unsigned int src_offset,
unsigned int src_len)
{
/* It be copied all in one go */
else {
/* Copy the two splits */
}
}
/* A memcmp against a cyclic data buffer. Compares SRC of length
* SRC_LEN data which begins at offset DEST_OFFSET in cyclic buffer
* DATA which is of size BUF_SIZE. Got that? Good. */
unsigned int dest_offset,
const unsigned char *src,
unsigned int src_len)
{
/* It be compared all in one go */
else {
/* Compare the two splits */
int diff;
if (diff) {
return diff;
}
}
}
/* Prototypes for low-level subcache operations */
UCHAR *, unsigned int);
/*
* High-Level "handlers" as per ssl_scache.c
* subcache internals are deferred to shmcb_subcache_*** functions lower down
*/
{
void *shm_segment;
{
void *data;
const char *userdata_key = "ssl_scache_init";
if (!data) {
return;
}
}
/* Create shared memory segment */
"SSLSessionCache required");
ssl_die();
}
/* Use anonymous shm by default, fall back on name-based. */
if (APR_STATUS_IS_ENOTIMPL(rv)) {
/* For a name-based segment, remove it first in case of a
* previous unclean shutdown. */
}
if (rv != APR_SUCCESS) {
"could not allocate shared memory for shmcb "
"session cache");
ssl_die();
}
/* the segment is ridiculously small, bail out */
"shared memory segment too small");
ssl_die();
}
"shmcb_init allocated %" APR_SIZE_T_FMT
" bytes of shared memory",
/* Discount the header */
shm_segsize -= sizeof(SHMCBHeader);
/* Select the number of subcaches to create and how many indexes each
* should contain based on the size of the memory (the header has already
* around 180 bytes (148 bytes data and 32 bytes for the id), so
* erring to division by 150 helps ensure we would exhaust data
* storage before index storage (except sslv2, where it's
* *slightly* the other way). From there, we select the number of
* subcaches to be a power of two, such that the number of indexes
* per subcache at least twice the number of subcaches. */
num_subcache = 256;
num_subcache /= 2;
num_idx /= num_subcache;
" including header), recommending %u subcaches, "
"%u indexes each", shm_segsize,
if (num_idx < 5) {
/* we're still too small, bail out */
"shared memory segment too small");
ssl_die();
}
/* OK, we're sorted */
header->stat_stores = 0;
header->stat_expiries = 0;
header->stat_scrolled = 0;
header->stat_retrieves_hit = 0;
header->stat_retrieves_miss = 0;
header->stat_removes_hit = 0;
header->stat_removes_miss = 0;
/* Convert the subcache size (in bytes) to a value that is suitable for
* structure alignment on the host platform, by rounding down if necessary.
* This assumes that sizeof(unsigned long) provides an appropriate
* alignment unit. */
~(size_t)(sizeof(unsigned long) - 1));
num_idx * sizeof(SHMCBIndex);
/* Output trace info */
"shmcb_init_memory choices follow");
/* The header is done, make the caches empty */
}
"Shared memory session cache initialised");
/* Success ... */
}
static void ssl_scache_shmcb_kill(server_rec *s)
{
}
return;
}
unsigned char *encoded,
unsigned int len_encoded)
{
ssl_mutex_on(s);
"ssl_scache_shmcb_store (0x%02x -> subcache %d)",
if (idlen < 4) {
"(%u bytes)", idlen);
goto done;
}
"can't store a session!");
goto done;
}
header->stat_stores++;
"leaving ssl_scache_shmcb_store successfully");
done:
ssl_mutex_off(s);
return to_return;
}
apr_pool_t *p)
{
ssl_mutex_on(s);
"ssl_scache_shmcb_retrieve (0x%02x -> subcache %d)",
/* Get the session corresponding to the session_id or NULL if it doesn't
* exist (or is flagged as "removed"). */
if (rv)
else
"leaving ssl_scache_shmcb_retrieve successfully");
ssl_mutex_off(s);
return rv;
}
{
ssl_mutex_on(s);
"ssl_scache_shmcb_remove (0x%02x -> subcache %d)",
if (idlen < 4) {
"(%u bytes)", idlen);
goto done;
}
else
"leaving ssl_scache_shmcb_remove successfully");
done:
ssl_mutex_off(s);
}
{
server_rec *s = r->server;
double expiry_total = 0;
/* Perform the iteration inside the mutex to avoid corruption or invalid
* pointer arithmetic. The rest of our logic uses read-only header data so
* doesn't need the lock. */
ssl_mutex_on(s);
/* Iterate over the subcaches */
expiry_total += (double)idx_expiry;
if (!min_expiry)
else
}
}
ssl_mutex_off(s);
/* Generate HTML */
ap_rprintf(r, "cache type: <b>SHMCB</b>, shared memory: <b>%d</b> "
"bytes, current sessions: <b>%d</b><br>",
ap_rprintf(r, "subcaches: <b>%d</b>, indexes per subcache: <b>%d</b><br>",
if (non_empty_subcaches) {
ap_rprintf(r, "time left on oldest entries' SSL sessions: ");
if (now < average_expiry)
ap_rprintf(r, "avg: <b>%d</b> seconds, (range: %d...%d)<br>",
(int)(average_expiry - now),
(int)(min_expiry - now),
(int)(max_expiry - now));
else
ap_rprintf(r, "expiry_threshold: <b>Calculation error!</b><br>");
}
ap_rprintf(r, "index usage: <b>%d%%</b>, cache usage: <b>%d%%</b><br>",
ap_rprintf(r, "total sessions stored since starting: <b>%lu</b><br>",
ap_rprintf(r, "total sessions expired since starting: <b>%lu</b><br>",
ap_rprintf(r, "total (pre-expiry) sessions scrolled out of the cache: "
ap_rprintf(r, "total retrieves since starting: <b>%lu</b> hit, "
ap_rprintf(r, "total removes since starting: <b>%lu</b> hit, "
}
/*
* Subcache-level cache operations
*/
{
unsigned int loop = 0;
/* it hasn't expired yet, we're done iterating */
break;
loop++;
}
if (!loop)
/* Nothing to do */
return;
"will be expiring %u sessions", loop);
/* We're expiring everything, piece of cake */
} else {
/* There remain other indexes, so we can use idx to adjust 'data' */
/* Adjust the indexes */
/* Adjust the data area */
}
}
{
/* Sanity check the input */
"inserting session larger (%d) than subcache data area (%d)",
return FALSE;
}
/* If there are entries to expire, ditch them first. */
/* Loop until there is enough space to insert */
unsigned int loop = 0;
"about to force-expire, subcache: idx_used=%d, "
do {
/* Adjust the indexes by one */
/* There's nothing left */
break;
}
/* Adjust the data */
/* Stats */
header->stat_scrolled++;
/* Loop admin */
loop++;
"finished force-expire, subcache: idx_used=%d, "
}
/* HERE WE ASSUME THAT THE NEW SESSION SHOULD GO ON THE END! I'M NOT
* CHECKING WHETHER IT SHOULD BE GENUINELY "INSERTED" SOMEWHERE.
*
* We either fix that, or find out at a "higher" (read "mod_ssl")
* level whether it is possible to have distinct session caches for
* any attempted tomfoolery to do with different session timeouts.
* Knowing in advance that we can have a cache-wide constant timeout
* would make this stuff *MUCH* more efficient. Mind you, it's very
* efficient right now because I'm ignoring this problem!!!
*/
/* Insert the id */
/* Insert the data */
/* Insert the index */
"insert happened at idx=%d, data=(%u:%u)", new_idx,
return TRUE;
}
{
unsigned int pos;
unsigned int loop = 0;
/* If there are entries to expire, ditch them first. */
/* Only consider 'idx' if the id matches, and the "removed"
* flag isn't set; check the data length too to avoid a buffer
* overflow in case of corruption, which should be impossible,
* but it's cheap to be safe. */
unsigned int data_offset;
/* Find the offset of the data segment, after the id */
/* Copy out the data */
data_offset, *destlen);
return TRUE;
}
/* Increment */
loop++;
}
"shmcb_subcache_retrieve found no match");
return FALSE;
}
{
unsigned int pos;
unsigned int loop = 0;
/* Unlike the others, we don't do an expire-run first. This is to keep
* consistent statistics where a "remove" operation may actually be the
* higher layer spotting an expiry issue prior to us. Our caller is
* handling stats, so a failure return would be inconsistent if the
* intended session was in fact removed by an expiry run. */
/* Only consider 'idx' if the id matches, and the "removed"
* flag isn't set. */
/* Found the matching session, remove it quietly. */
"shmcb_subcache_remove removing matching session");
}
/* Increment */
loop++;
}
return to_return;
}
};