libwebsockets
Lightweight C library for HTML5 websockets
lws-fault-injection.h
Go to the documentation of this file.
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  *
24  * Fault injection api if built with LWS_WITH_SYS_FAULT_INJECTION
25  */
26 
27 typedef struct lws_xos {
28  uint64_t s[4];
29 } lws_xos_t;
30 
31 /**
32  * lws_xos_init() - seed xoshiro256 PRNG
33  *
34  * \param xos: the prng state object to initialize
35  * \param seed: the 64-bit seed
36  *
37  * Initialize PRNG \xos with the starting state represented by \p seed
38  */
39 LWS_VISIBLE LWS_EXTERN void
40 lws_xos_init(struct lws_xos *xos, uint64_t seed);
41 
42 /**
43  * lws_xos() - get next xoshiro256 PRNG result and update state
44  *
45  * \param xos: the PRNG state to use
46  *
47  * Returns next 64-bit PRNG result. These are cheap to get,
48  * quite a white noise sequence, and completely deterministic
49  * according to the seed it was initialized with.
50  */
51 LWS_VISIBLE LWS_EXTERN uint64_t LWS_WARN_UNUSED_RESULT
52 lws_xos(struct lws_xos *xos);
53 
54 /**
55  * lws_xos_percent() - return 1 a given percent of the time on average
56  *
57  * \param xos: the PRNG state to use
58  * \param percent: chance in 100 of returning 1
59  *
60  * Returns 1 if next random % 100 is < \p percent, such that
61  * 100 always returns 1, 0 never returns 1, and the chance linearly scales
62  * inbetween
63  */
64 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
65 lws_xos_percent(struct lws_xos *xos, int percent);
66 
67 #if defined(LWS_WITH_SYS_FAULT_INJECTION)
68 
69 enum {
70  LWSFI_ALWAYS,
71  LWSFI_DETERMINISTIC, /* do .count injections after .pre then stop */
72  LWSFI_PROBABILISTIC, /* .pre % chance of injection */
73  LWSFI_PATTERN, /* use .count bits in .pattern after .pre */
74  LWSFI_PATTERN_ALLOC, /* as _PATTERN, but .pattern is malloc'd */
75  LWSFI_RANGE /* pick a number between pre and count */
76 };
77 
78 typedef struct lws_fi {
79  const char *name;
80  const uint8_t *pattern;
81  uint64_t pre;
82  uint64_t count;
83  uint64_t times; /* start at 0, tracks usage */
84  char type; /* LWSFI_* */
85 } lws_fi_t;
86 
87 typedef struct lws_fi_ctx {
88  lws_dll2_owner_t fi_owner;
89  struct lws_xos xos;
90  const char *name;
91 } lws_fi_ctx_t;
92 
93 /**
94  * lws_fi() - find out if we should perform the named fault injection this time
95  *
96  * \param fic: fault injection tracking context
97  * \param fi_name: name of fault injection
98  *
99  * This checks if the named fault is configured in the fi tracking context
100  * provided, if it is, then it will make a decision if the named fault should
101  * be applied this time, using the tracking in the named lws_fi_t.
102  *
103  * If the provided context has a parent, that is also checked for the named fi
104  * item recursively, with the first found being used to determine if to inject
105  * or not.
106  *
107  * If LWS_WITH_SYS_FAULT_INJECTION is not defined, then this always return 0.
108  */
109 LWS_VISIBLE LWS_EXTERN int
110 lws_fi(const lws_fi_ctx_t *fic, const char *fi_name);
111 
112 /**
113  * lws_fi_range() - get a random number from a range
114  *
115  * \param fic: fault injection tracking context
116  * \param fi_name: name of fault injection
117  * \param result: points to uint64_t to be set to the result
118  *
119  * This lets you get a random number from an externally-set range, set using a
120  * fault injection syntax like "myfault(123..456)". That will cause us to
121  * return a number between those two inclusive, from the seeded PRNG.
122  *
123  * This is useful when you used lws_fi() with its own fault name to decide
124  * whether to inject the fault, and then the code to cause the fault needs
125  * additional constrained pseudo-random fuzzing for, eg, delays before issuing
126  * the fault.
127  *
128  * Returns 0 if \p *result is set, else nonzero for failure.
129  */
130 LWS_VISIBLE LWS_EXTERN int
131 lws_fi_range(const lws_fi_ctx_t *fic, const char *name, uint64_t *result);
132 
133 /**
134  * lws_fi_add() - add an allocated copy of fault injection to a context
135  *
136  * \param fic: fault injection tracking context
137  * \param fi: the fault injection details
138  *
139  * This allocates a copy of \p fi and attaches it to the fault injection context
140  * \p fic. \p fi can go out of scope after this safely.
141  */
142 LWS_VISIBLE LWS_EXTERN int
143 lws_fi_add(lws_fi_ctx_t *fic, const lws_fi_t *fi);
144 
145 /**
146  * lws_fi_remove() - remove an allocated copy of fault injection from a context
147  *
148  * \param fic: fault injection tracking context
149  * \param name: the fault injection name to remove
150  *
151  * This looks for the named fault injection and removes and destroys it from
152  * the specified fault injection context
153  */
154 LWS_VISIBLE LWS_EXTERN void
155 lws_fi_remove(lws_fi_ctx_t *fic, const char *name);
156 
157 /**
158  * lws_fi_import() - transfers all the faults from one context to another
159  *
160  * \param fic_dest: the fault context to receive the faults
161  * \param fic_src: the fault context that will be emptied out into \p fic_dest
162  *
163  * This is used to initialize created object fault injection contexts from
164  * the caller.
165  */
166 LWS_VISIBLE LWS_EXTERN void
167 lws_fi_import(lws_fi_ctx_t *fic_dest, const lws_fi_ctx_t *fic_src);
168 
169 /**
170  * lws_fi_inherit_copy() - attach copies of matching fault injection objects to dest
171  *
172  * \param fic_dest: destination Fault Injection context
173  * \param fic_src: parent fault context that may contain matching rules
174  * \param scope: the name of the path match required, eg, "vh"
175  * \param value: the dynamic name of our match, eg, "myvhost"
176  *
177  * If called with scope "vh" and value "myvhost", then matches faults starting
178  * "vh=myvhost/", strips that part of the name if it matches and makes a copy
179  * of the rule with the modified name attached to the destination Fault Injection
180  * context.
181  */
182 LWS_VISIBLE LWS_EXTERN void
183 lws_fi_inherit_copy(lws_fi_ctx_t *fic_dest, const lws_fi_ctx_t *fic_src,
184  const char *scope, const char *value);
185 
186 /**
187  * lws_fi_destroy() - removes all allocated fault injection entries
188  *
189  * \param fic: fault injection tracking context
190  *
191  * This walks any allocated fault injection entries in \p fic and detaches and
192  * destroys them. It doesn't try to destroc \p fic itself, since this is
193  * not usually directly allocated.
194  */
195 LWS_VISIBLE LWS_EXTERN void
196 lws_fi_destroy(const lws_fi_ctx_t *fic);
197 
198 /**
199  * lws_fi_deserialize() - adds fault in string form to Fault Injection Context
200  *
201  * \p fic: the fault injection context
202  * \p sers: the string serializing the desired fault details
203  *
204  * This turns a string like "ss=captive_portal_detect/wsi/dnsfail(10%)" into
205  * a fault injection struct added to the fault injection context \p fic
206  *
207  * You can prepare the context creation info .fic with these before creating
208  * the context, and use namespace paths on those to target other objects.
209  */
210 
211 LWS_VISIBLE LWS_EXTERN void
212 lws_fi_deserialize(lws_fi_ctx_t *fic, const char *sers);
213 
214 LWS_VISIBLE LWS_EXTERN int
215 _lws_fi_user_wsi_fi(struct lws *wsi, const char *name);
216 LWS_VISIBLE LWS_EXTERN int
217 _lws_fi_user_context_fi(struct lws_context *ctx, const char *name);
218 
219 #if defined(LWS_WITH_SECURE_STREAMS)
220 struct lws_ss_handle;
221 LWS_VISIBLE LWS_EXTERN int
222 _lws_fi_user_ss_fi(struct lws_ss_handle *h, const char *name);
223 #if defined(LWS_WITH_SECURE_STREAMS_PROXY_API)
224 struct lws_sspc_handle;
225 LWS_VISIBLE LWS_EXTERN int
226 _lws_fi_user_sspc_fi(struct lws_sspc_handle *h, const char *name);
227 #endif
228 #endif
229 
230 #define lws_fi_user_wsi_fi(_wsi, _name) _lws_fi_user_wsi_fi(_wsi, _name)
231 #define lws_fi_user_context_fi(_ctx, _name) _lws_fi_user_context_fi(_ctx, _name)
232 #define lws_fi_user_ss_fi(_h, _name) _lws_fi_user_ss_fi(_h, _name)
233 #define lws_fi_user_sspc_fi(_h, _name) _lws_fi_user_sspc_fi(_h, _name)
234 
235 #else
236 
237 /*
238  * Helper so we can leave lws_fi() calls embedded in the code being tested,
239  * if fault injection is not enabled then it just always says "no" at buildtime.
240  */
241 
242 #define lws_fi(_fi_name, _fic) (0)
243 #define lws_fi_destroy(_x)
244 #define lws_fi_inherit_copy(_a, _b, _c, _d)
245 #define lws_fi_deserialize(_x, _y)
246 #define lws_fi_user_wsi_fi(_wsi, _name) (0)
247 #define lws_fi_user_context_fi(_wsi, _name) (0)
248 #define lws_fi_user_ss_fi(_h, _name) (0)
249 #define lws_fi_user_sspc_fi(_h, _name) (0)
250 
251 #endif