suricata
util-spm-hs.c
Go to the documentation of this file.
1 /* Copyright (C) 2016-2023 Open Information Security Foundation
2  *
3  * You can copy, redistribute or modify this Program under the terms of
4  * the GNU General Public License version 2 as published by the Free
5  * Software Foundation.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * version 2 along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
15  * 02110-1301, USA.
16  */
17 
18 /**
19  * \file
20  *
21  * \author Justin Viiret <justin.viiret@intel.com>
22  *
23  * Single pattern matcher that uses the Hyperscan regex matcher.
24  */
25 
26 #include "suricata-common.h"
27 #include "util-hyperscan.h"
28 #include "util-spm.h"
29 #include "util-spm-hs.h"
30 #include "util-debug.h"
31 
32 #ifdef BUILD_HYPERSCAN
33 
34 #include <hs.h>
35 
36 /**
37  * \internal
38  * \brief Hyperscan match callback, called by hs_scan.
39  */
40 static int MatchEvent(unsigned int id, unsigned long long from,
41  unsigned long long to, unsigned int flags, void *context)
42 {
43  uint64_t *match_offset = context;
44  BUG_ON(*match_offset != UINT64_MAX);
45  *match_offset = to;
46  return 1; /* Terminate matching. */
47 }
48 
49 typedef struct SpmHsCtx_ {
50  hs_database_t *db;
51  uint16_t needle_len;
52 } SpmHsCtx;
53 
54 static void HSDestroyCtx(SpmCtx *ctx)
55 {
56  if (ctx == NULL) {
57  return;
58  }
59  SpmHsCtx *sctx = ctx->ctx;
60  if (sctx) {
61  hs_free_database(sctx->db);
62  SCFree(sctx);
63  }
64  SCFree(ctx);
65 }
66 
67 static int HSBuildDatabase(const uint8_t *needle, uint16_t needle_len,
68  int nocase, SpmHsCtx *sctx,
69  SpmGlobalThreadCtx *global_thread_ctx)
70 {
71  char *expr = HSRenderPattern(needle, needle_len);
72  if (expr == NULL) {
73  SCLogDebug("HSRenderPattern returned NULL");
74  return -1;
75  }
76 
77  unsigned flags = nocase ? HS_FLAG_CASELESS : 0;
78 
79  hs_database_t *db = NULL;
80  hs_compile_error_t *compile_err = NULL;
81  hs_error_t err = hs_compile(expr, flags, HS_MODE_BLOCK, NULL, &db,
82  &compile_err);
83  if (err != HS_SUCCESS) {
84  SCLogError("Unable to compile '%s' with Hyperscan, "
85  "returned %d.",
86  expr, err);
87  return -1;
88  }
89 
90  SCFree(expr);
91 
92  /* Update scratch for this database. */
93  hs_scratch_t *scratch = global_thread_ctx->ctx;
94  err = hs_alloc_scratch(db, &scratch);
95  if (err != HS_SUCCESS) {
96  /* If scratch allocation failed, this is not recoverable: other SPM
97  * contexts may need this scratch space. */
98  SCLogError("Unable to alloc scratch for Hyperscan, returned %d.", err);
99  return -1;
100  }
101  global_thread_ctx->ctx = scratch;
102  sctx->db = db;
103  sctx->needle_len = needle_len;
104 
105  return 0;
106 }
107 
108 static SpmCtx *HSInitCtx(const uint8_t *needle, uint16_t needle_len, int nocase,
109  SpmGlobalThreadCtx *global_thread_ctx)
110 {
111  SpmCtx *ctx = SCCalloc(1, sizeof(SpmCtx));
112  if (ctx == NULL) {
113  SCLogDebug("Unable to alloc SpmCtx.");
114  return NULL;
115  }
116  ctx->matcher = SPM_HS;
117 
118  SpmHsCtx *sctx = SCCalloc(1, sizeof(SpmHsCtx));
119  if (sctx == NULL) {
120  SCLogDebug("Unable to alloc SpmHsCtx.");
121  SCFree(ctx);
122  return NULL;
123  }
124  ctx->ctx = sctx;
125 
126  if (HSBuildDatabase(needle, needle_len, nocase, sctx,
127  global_thread_ctx) != 0) {
128  SCLogDebug("HSBuildDatabase failed.");
129  HSDestroyCtx(ctx);
130  return NULL;
131  }
132 
133  return ctx;
134 }
135 
136 static uint8_t *HSScan(const SpmCtx *ctx, SpmThreadCtx *thread_ctx,
137  const uint8_t *haystack, uint32_t haystack_len)
138 {
139  const SpmHsCtx *sctx = ctx->ctx;
140  hs_scratch_t *scratch = thread_ctx->ctx;
141 
142  if (unlikely(haystack_len == 0)) {
143  return NULL;
144  }
145 
146  uint64_t match_offset = UINT64_MAX;
147  hs_error_t err = hs_scan(sctx->db, (const char *)haystack, haystack_len, 0,
148  scratch, MatchEvent, &match_offset);
149  if (err != HS_SUCCESS && err != HS_SCAN_TERMINATED) {
150  /* An error value (other than HS_SCAN_TERMINATED) from hs_scan()
151  * indicates that it was passed an invalid database or scratch region,
152  * which is not something we can recover from at scan time. */
153  SCLogError("Hyperscan returned fatal error %d.", err);
154  exit(EXIT_FAILURE);
155  }
156 
157  if (match_offset == UINT64_MAX) {
158  return NULL;
159  }
160 
161  BUG_ON(match_offset < sctx->needle_len);
162 
163  /* Note: existing API returns non-const ptr */
164  return (uint8_t *)haystack + (match_offset - sctx->needle_len);
165 }
166 
167 static SpmGlobalThreadCtx *HSInitGlobalThreadCtx(void)
168 {
169  SpmGlobalThreadCtx *global_thread_ctx = SCCalloc(1, sizeof(SpmGlobalThreadCtx));
170  if (global_thread_ctx == NULL) {
171  SCLogDebug("Unable to alloc SpmGlobalThreadCtx.");
172  return NULL;
173  }
174  global_thread_ctx->matcher = SPM_HS;
175 
176  /* We store scratch in the HS-specific ctx. This will be initialized as
177  * patterns are compiled by SpmInitCtx. */
178  global_thread_ctx->ctx = NULL;
179 
180  return global_thread_ctx;
181 }
182 
183 static void HSDestroyGlobalThreadCtx(SpmGlobalThreadCtx *global_thread_ctx)
184 {
185  if (global_thread_ctx == NULL) {
186  return;
187  }
188  hs_free_scratch(global_thread_ctx->ctx);
189  SCFree(global_thread_ctx);
190 }
191 
192 static void HSDestroyThreadCtx(SpmThreadCtx *thread_ctx)
193 {
194  if (thread_ctx == NULL) {
195  return;
196  }
197  hs_free_scratch(thread_ctx->ctx);
198  SCFree(thread_ctx);
199 }
200 
201 static SpmThreadCtx *HSMakeThreadCtx(const SpmGlobalThreadCtx *global_thread_ctx)
202 {
203  SpmThreadCtx *thread_ctx = SCCalloc(1, sizeof(SpmThreadCtx));
204  if (thread_ctx == NULL) {
205  SCLogDebug("Unable to alloc SpmThreadCtx.");
206  return NULL;
207  }
208  thread_ctx->matcher = SPM_HS;
209 
210  if (global_thread_ctx->ctx != NULL) {
211  hs_scratch_t *scratch = NULL;
212  hs_error_t err = hs_clone_scratch(global_thread_ctx->ctx, &scratch);
213  if (err != HS_SUCCESS) {
214  SCLogError("Unable to clone scratch (error %d).", err);
215  exit(EXIT_FAILURE);
216  }
217  thread_ctx->ctx = scratch;
218  }
219 
220  return thread_ctx;
221 }
222 
223 void SpmHSRegister(void)
224 {
225  spm_table[SPM_HS].name = "hs";
226  spm_table[SPM_HS].InitGlobalThreadCtx = HSInitGlobalThreadCtx;
227  spm_table[SPM_HS].DestroyGlobalThreadCtx = HSDestroyGlobalThreadCtx;
228  spm_table[SPM_HS].MakeThreadCtx = HSMakeThreadCtx;
229  spm_table[SPM_HS].DestroyThreadCtx = HSDestroyThreadCtx;
230  spm_table[SPM_HS].InitCtx = HSInitCtx;
231  spm_table[SPM_HS].DestroyCtx = HSDestroyCtx;
232  spm_table[SPM_HS].Scan = HSScan;
233 }
234 
235 #endif /* BUILD_HYPERSCAN */
SpmThreadCtx_::ctx
void * ctx
Definition: util-spm.h:56
SpmCtx_::matcher
uint8_t matcher
Definition: util-spm.h:41
unlikely
#define unlikely(expr)
Definition: util-optimize.h:35
SpmTableElmt_::Scan
uint8_t *(* Scan)(const SpmCtx *ctx, SpmThreadCtx *thread_ctx, const uint8_t *haystack, uint32_t haystack_len)
Definition: util-spm.h:68
SCLogDebug
#define SCLogDebug(...)
Definition: util-debug.h:269
SpmTableElmt_::InitCtx
SpmCtx *(* InitCtx)(const uint8_t *needle, uint16_t needle_len, int nocase, SpmGlobalThreadCtx *g_thread_ctx)
Definition: util-spm.h:65
SpmTableElmt_::name
const char * name
Definition: util-spm.h:60
SpmTableElmt_::MakeThreadCtx
SpmThreadCtx *(* MakeThreadCtx)(const SpmGlobalThreadCtx *g_thread_ctx)
Definition: util-spm.h:63
util-hyperscan.h
SPM_HS
@ SPM_HS
Definition: util-spm.h:31
util-debug.h
BUG_ON
#define BUG_ON(x)
Definition: suricata-common.h:300
SpmTableElmt_::InitGlobalThreadCtx
SpmGlobalThreadCtx *(* InitGlobalThreadCtx)(void)
Definition: util-spm.h:61
SpmGlobalThreadCtx_::matcher
uint8_t matcher
Definition: util-spm.h:48
SpmCtx_
Definition: util-spm.h:40
flags
uint8_t flags
Definition: decode-gre.h:0
suricata-common.h
SpmTableElmt_::DestroyCtx
void(* DestroyCtx)(SpmCtx *)
Definition: util-spm.h:67
util-spm.h
SpmCtx_::ctx
void * ctx
Definition: util-spm.h:42
SpmGlobalThreadCtx_::ctx
void * ctx
Definition: util-spm.h:49
HSRenderPattern
char * HSRenderPattern(const uint8_t *pat, uint16_t pat_len)
util-spm-hs.h
SpmGlobalThreadCtx_
Definition: util-spm.h:47
SCLogError
#define SCLogError(...)
Macro used to log ERROR messages.
Definition: util-debug.h:261
SCFree
#define SCFree(p)
Definition: util-mem.h:61
spm_table
SpmTableElmt spm_table[SPM_TABLE_SIZE]
Definition: util-spm.c:62
SpmHSRegister
void SpmHSRegister(void)
SpmThreadCtx_::matcher
uint8_t matcher
Definition: util-spm.h:55
SCCalloc
#define SCCalloc(nm, sz)
Definition: util-mem.h:53
SpmTableElmt_::DestroyThreadCtx
void(* DestroyThreadCtx)(SpmThreadCtx *thread_ctx)
Definition: util-spm.h:64
SpmTableElmt_::DestroyGlobalThreadCtx
void(* DestroyGlobalThreadCtx)(SpmGlobalThreadCtx *g_thread_ctx)
Definition: util-spm.h:62
SpmThreadCtx_
Definition: util-spm.h:54