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
27typedef 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 */
39LWS_VISIBLE LWS_EXTERN void
40lws_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 */
51LWS_VISIBLE LWS_EXTERN uint64_t LWS_WARN_UNUSED_RESULT
52lws_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 */
64LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
65lws_xos_percent(struct lws_xos *xos, int percent);
66
67#if defined(LWS_WITH_SYS_FAULT_INJECTION)
68
69enum {
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
78typedef 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
87typedef 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 */
109LWS_VISIBLE LWS_EXTERN int
110lws_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 */
130LWS_VISIBLE LWS_EXTERN int
131lws_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 */
142LWS_VISIBLE LWS_EXTERN int
143lws_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 */
154LWS_VISIBLE LWS_EXTERN void
155lws_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 */
166LWS_VISIBLE LWS_EXTERN void
167lws_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 */
182LWS_VISIBLE LWS_EXTERN void
183lws_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 */
195LWS_VISIBLE LWS_EXTERN void
196lws_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
211LWS_VISIBLE LWS_EXTERN void
212lws_fi_deserialize(lws_fi_ctx_t *fic, const char *sers);
213
214LWS_VISIBLE LWS_EXTERN int
215_lws_fi_user_wsi_fi(struct lws *wsi, const char *name);
216LWS_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)
220struct lws_ss_handle;
221LWS_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)
224struct lws_sspc_handle;
225LWS_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
252