Branch data Line data Source code
1 : :
2 : : /*
3 : : * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 : : *
5 : : * Licensed under the Apache License, Version 2.0 (the "License").
6 : : * You may not use this file except in compliance with the License.
7 : : * A copy of the License is located at
8 : : *
9 : : * http://aws.amazon.com/apache2.0
10 : : *
11 : : * or in the "license" file accompanying this file. This file is distributed
12 : : * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
13 : : * express or implied. See the License for the specific language governing
14 : : * permissions and limitations under the License.
15 : : */
16 : :
17 : : #pragma once
18 : :
19 : : /**
20 : : * DO NOT DIRECTLY MODIFY THIS FILE:
21 : : *
22 : : * The code in this file is generated from scripts/s2n_safety_macros.py and any modifications
23 : : * should be in there.
24 : : */
25 : :
26 : : /* clang-format off */
27 : :
28 : : #include "error/s2n_errno.h"
29 : : #include "utils/s2n_ensure.h"
30 : : #include "utils/s2n_result.h"
31 : :
32 : : /**
33 : : * The goal of s2n_safety is to provide helpers to perform common
34 : : * checks, which help with code readability.
35 : : */
36 : :
37 : : /* Success signal value for OpenSSL functions */
38 : : #define _OSSL_SUCCESS 1
39 : :
40 : : /**
41 : : * Sets the global `s2n_errno` to `error` and returns with an `S2N_RESULT_ERROR`
42 : : */
43 : 643744 : #define RESULT_BAIL(error) do { _S2N_ERROR((error)); __S2N_ENSURE_CHECKED_RETURN(S2N_RESULT_ERROR); } while (0)
44 : :
45 : : /**
46 : : * Ensures the `condition` is `true`, otherwise the function will `RESULT_BAIL` with `error`
47 : : */
48 : 30696613 : #define RESULT_ENSURE(condition, error) __S2N_ENSURE((condition), RESULT_BAIL(error))
49 : :
50 : : /**
51 : : * Ensures the `condition` is `true`, otherwise the function will `RESULT_BAIL` with `error`
52 : : *
53 : : * NOTE: The condition will _only_ be checked when the code is compiled in debug mode.
54 : : * In release mode, the check is removed.
55 : : */
56 : 8984464210 : #define RESULT_DEBUG_ENSURE(condition, error) __S2N_ENSURE_DEBUG((condition), RESULT_BAIL(error))
57 : :
58 : : /**
59 : : * Ensures `s2n_result_is_ok(result)`, otherwise the function will `RESULT_BAIL` with `error`
60 : : *
61 : : * This can be useful for overriding the global `s2n_errno`
62 : : */
63 : 82 : #define RESULT_ENSURE_OK(result, error) __S2N_ENSURE(s2n_result_is_ok(result), RESULT_BAIL(error))
64 : :
65 : : /**
66 : : * Ensures `a` is greater than or equal to `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error
67 : : */
68 : 17097396 : #define RESULT_ENSURE_GTE(a, b) __S2N_ENSURE((a) >= (b), RESULT_BAIL(S2N_ERR_SAFETY))
69 : :
70 : : /**
71 : : * Ensures `a` is less than or equal to `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error
72 : : */
73 : 16709476 : #define RESULT_ENSURE_LTE(a, b) __S2N_ENSURE((a) <= (b), RESULT_BAIL(S2N_ERR_SAFETY))
74 : :
75 : : /**
76 : : * Ensures `a` is greater than `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error
77 : : */
78 : 395170 : #define RESULT_ENSURE_GT(a, b) __S2N_ENSURE((a) > (b), RESULT_BAIL(S2N_ERR_SAFETY))
79 : :
80 : : /**
81 : : * Ensures `a` is less than `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error
82 : : */
83 : 92177 : #define RESULT_ENSURE_LT(a, b) __S2N_ENSURE((a) < (b), RESULT_BAIL(S2N_ERR_SAFETY))
84 : :
85 : : /**
86 : : * Ensures `a` is equal to `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error
87 : : */
88 : 159663943 : #define RESULT_ENSURE_EQ(a, b) __S2N_ENSURE((a) == (b), RESULT_BAIL(S2N_ERR_SAFETY))
89 : :
90 : : /**
91 : : * Ensures `a` is not equal to `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error
92 : : */
93 : 8109302 : #define RESULT_ENSURE_NE(a, b) __S2N_ENSURE((a) != (b), RESULT_BAIL(S2N_ERR_SAFETY))
94 : :
95 : : /**
96 : : * Ensures `min <= n <= max`, otherwise the function will `RESULT_BAIL` with `S2N_ERR_SAFETY`
97 : : */
98 : : #define RESULT_ENSURE_INCLUSIVE_RANGE(min, n, max) \
99 : 386 : do { \
100 : 386 : __typeof(n) __tmp_n = ( n ); \
101 : 386 : __typeof(n) __tmp_min = ( min ); \
102 : 386 : __typeof(n) __tmp_max = ( max ); \
103 : 386 : RESULT_ENSURE_GTE(__tmp_n, __tmp_min); \
104 : 386 : RESULT_ENSURE_LTE(__tmp_n, __tmp_max); \
105 : 386 : } while(0)
106 : :
107 : : /**
108 : : * Ensures `min < n < max`, otherwise the function will `RESULT_BAIL` with `S2N_ERR_SAFETY`
109 : : */
110 : : #define RESULT_ENSURE_EXCLUSIVE_RANGE(min, n, max) \
111 : : do { \
112 : : __typeof(n) __tmp_n = ( n ); \
113 : : __typeof(n) __tmp_min = ( min ); \
114 : : __typeof(n) __tmp_max = ( max ); \
115 : : RESULT_ENSURE_GT(__tmp_n, __tmp_min); \
116 : : RESULT_ENSURE_LT(__tmp_n, __tmp_max); \
117 : : } while(0)
118 : :
119 : : /**
120 : : * Ensures `x` is a readable reference, otherwise the function will `RESULT_BAIL` with `S2N_ERR_NULL`
121 : : */
122 : 2061568956 : #define RESULT_ENSURE_REF(x) __S2N_ENSURE(S2N_OBJECT_PTR_IS_READABLE(x), RESULT_BAIL(S2N_ERR_NULL))
123 : :
124 : : /**
125 : : * Ensures `x` is a mutable reference, otherwise the function will `RESULT_BAIL` with `S2N_ERR_NULL`
126 : : */
127 : 10552270 : #define RESULT_ENSURE_MUT(x) __S2N_ENSURE(S2N_OBJECT_PTR_IS_WRITABLE(x), RESULT_BAIL(S2N_ERR_NULL))
128 : :
129 : : /**
130 : : * Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal
131 : : *
132 : : * `RESULT_PRECONDITION` should be used at the beginning of a function to make assertions about
133 : : * the provided arguments. By default, it is functionally equivalent to `RESULT_GUARD(result)`
134 : : * but can be altered by a testing environment to provide additional guarantees.
135 : : */
136 : 917485 : #define RESULT_PRECONDITION(result) RESULT_GUARD(__S2N_ENSURE_PRECONDITION((result)))
137 : :
138 : : /**
139 : : * Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal
140 : : *
141 : : * NOTE: The condition will _only_ be checked when the code is compiled in debug mode.
142 : : * In release mode, the check is removed.
143 : : *
144 : : * `RESULT_POSTCONDITION` should be used at the end of a function to make assertions about
145 : : * the resulting state. In debug mode, it is functionally equivalent to `RESULT_GUARD(result)`.
146 : : * In production builds, it becomes a no-op. This can also be altered by a testing environment
147 : : * to provide additional guarantees.
148 : : */
149 : 6974079 : #define RESULT_POSTCONDITION(result) RESULT_GUARD(__S2N_ENSURE_POSTCONDITION((result)))
150 : :
151 : : /**
152 : : * Performs a safer memcpy.
153 : : *
154 : : * The following checks are performed:
155 : : *
156 : : * * `destination` is non-null
157 : : * * `source` is non-null
158 : : *
159 : : * Callers will still need to ensure the following:
160 : : *
161 : : * * The size of the data pointed to by both the `destination` and `source` parameters,
162 : : * shall be at least `len` bytes.
163 : : */
164 : 4913616 : #define RESULT_CHECKED_MEMCPY(destination, source, len) __S2N_ENSURE_SAFE_MEMMOVE((destination), (source), (len), RESULT_ENSURE_REF)
165 : :
166 : : /**
167 : : * Performs a safer memset
168 : : *
169 : : * The following checks are performed:
170 : : *
171 : : * * `destination` is non-null
172 : : *
173 : : * Callers will still need to ensure the following:
174 : : *
175 : : * * The size of the data pointed to by the `destination` parameter shall be at least
176 : : * `len` bytes.
177 : : */
178 : 13938154 : #define RESULT_CHECKED_MEMSET(destination, value, len) __S2N_ENSURE_SAFE_MEMSET((destination), (value), (len), RESULT_ENSURE_REF)
179 : :
180 : : /**
181 : : * Ensures `s2n_result_is_ok(result)`, otherwise the function will return `S2N_RESULT_ERROR`
182 : : */
183 : 1052379217 : #define RESULT_GUARD(result) __S2N_ENSURE(s2n_result_is_ok(result), __S2N_ENSURE_CHECKED_RETURN(S2N_RESULT_ERROR))
184 : :
185 : : /**
186 : : * Ensures `result == _OSSL_SUCCESS`, otherwise the function will `RESULT_BAIL` with `error`
187 : : */
188 : 171546159 : #define RESULT_GUARD_OSSL(result, error) __S2N_ENSURE((result) == _OSSL_SUCCESS, RESULT_BAIL(error))
189 : :
190 : : /**
191 : : * Ensures `(result) > S2N_FAILURE`, otherwise the function will return `S2N_RESULT_ERROR`
192 : : */
193 : 130172019 : #define RESULT_GUARD_POSIX(result) __S2N_ENSURE((result) > S2N_FAILURE, __S2N_ENSURE_CHECKED_RETURN(S2N_RESULT_ERROR))
194 : :
195 : : /**
196 : : * Ensures `(result) != NULL`, otherwise the function will return `S2N_RESULT_ERROR`
197 : : *
198 : : * Does not set s2n_errno to S2N_ERR_NULL, so is NOT a direct replacement for RESULT_ENSURE_REF.
199 : : */
200 : 9192450 : #define RESULT_GUARD_PTR(result) __S2N_ENSURE((result) != NULL, __S2N_ENSURE_CHECKED_RETURN(S2N_RESULT_ERROR))
201 : :
202 : : /**
203 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
204 : : *
205 : : * Sets the global `s2n_errno` to `error` and returns with an `S2N_FAILURE`
206 : : */
207 : 21145 : #define POSIX_BAIL(error) do { _S2N_ERROR((error)); __S2N_ENSURE_CHECKED_RETURN(S2N_FAILURE); } while (0)
208 : :
209 : : /**
210 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
211 : : *
212 : : * Ensures the `condition` is `true`, otherwise the function will `POSIX_BAIL` with `error`
213 : : */
214 : 827993821 : #define POSIX_ENSURE(condition, error) __S2N_ENSURE((condition), POSIX_BAIL(error))
215 : :
216 : : /**
217 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
218 : : *
219 : : * Ensures the `condition` is `true`, otherwise the function will `POSIX_BAIL` with `error`
220 : : *
221 : : * NOTE: The condition will _only_ be checked when the code is compiled in debug mode.
222 : : * In release mode, the check is removed.
223 : : */
224 : : #define POSIX_DEBUG_ENSURE(condition, error) __S2N_ENSURE_DEBUG((condition), POSIX_BAIL(error))
225 : :
226 : : /**
227 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
228 : : *
229 : : * Ensures `(result) > S2N_FAILURE`, otherwise the function will `POSIX_BAIL` with `error`
230 : : *
231 : : * This can be useful for overriding the global `s2n_errno`
232 : : */
233 : 545 : #define POSIX_ENSURE_OK(result, error) __S2N_ENSURE((result) > S2N_FAILURE, POSIX_BAIL(error))
234 : :
235 : : /**
236 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
237 : : *
238 : : * Ensures `a` is greater than or equal to `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error
239 : : */
240 : 64336388 : #define POSIX_ENSURE_GTE(a, b) __S2N_ENSURE((a) >= (b), POSIX_BAIL(S2N_ERR_SAFETY))
241 : :
242 : : /**
243 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
244 : : *
245 : : * Ensures `a` is less than or equal to `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error
246 : : */
247 : 11835076 : #define POSIX_ENSURE_LTE(a, b) __S2N_ENSURE((a) <= (b), POSIX_BAIL(S2N_ERR_SAFETY))
248 : :
249 : : /**
250 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
251 : : *
252 : : * Ensures `a` is greater than `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error
253 : : */
254 : 343885 : #define POSIX_ENSURE_GT(a, b) __S2N_ENSURE((a) > (b), POSIX_BAIL(S2N_ERR_SAFETY))
255 : :
256 : : /**
257 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
258 : : *
259 : : * Ensures `a` is less than `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error
260 : : */
261 : 3651717 : #define POSIX_ENSURE_LT(a, b) __S2N_ENSURE((a) < (b), POSIX_BAIL(S2N_ERR_SAFETY))
262 : :
263 : : /**
264 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
265 : : *
266 : : * Ensures `a` is equal to `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error
267 : : */
268 : 9046232 : #define POSIX_ENSURE_EQ(a, b) __S2N_ENSURE((a) == (b), POSIX_BAIL(S2N_ERR_SAFETY))
269 : :
270 : : /**
271 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
272 : : *
273 : : * Ensures `a` is not equal to `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error
274 : : */
275 : 3634019 : #define POSIX_ENSURE_NE(a, b) __S2N_ENSURE((a) != (b), POSIX_BAIL(S2N_ERR_SAFETY))
276 : :
277 : : /**
278 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
279 : : *
280 : : * Ensures `min <= n <= max`, otherwise the function will `POSIX_BAIL` with `S2N_ERR_SAFETY`
281 : : */
282 : : #define POSIX_ENSURE_INCLUSIVE_RANGE(min, n, max) \
283 : 882067 : do { \
284 : 882067 : __typeof(n) __tmp_n = ( n ); \
285 : 882067 : __typeof(n) __tmp_min = ( min ); \
286 : 882067 : __typeof(n) __tmp_max = ( max ); \
287 : 882067 : POSIX_ENSURE_GTE(__tmp_n, __tmp_min); \
288 : 882067 : POSIX_ENSURE_LTE(__tmp_n, __tmp_max); \
289 : 882067 : } while(0)
290 : :
291 : : /**
292 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
293 : : *
294 : : * Ensures `min < n < max`, otherwise the function will `POSIX_BAIL` with `S2N_ERR_SAFETY`
295 : : */
296 : : #define POSIX_ENSURE_EXCLUSIVE_RANGE(min, n, max) \
297 : : do { \
298 : : __typeof(n) __tmp_n = ( n ); \
299 : : __typeof(n) __tmp_min = ( min ); \
300 : : __typeof(n) __tmp_max = ( max ); \
301 : : POSIX_ENSURE_GT(__tmp_n, __tmp_min); \
302 : : POSIX_ENSURE_LT(__tmp_n, __tmp_max); \
303 : : } while(0)
304 : :
305 : : /**
306 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
307 : : *
308 : : * Ensures `x` is a readable reference, otherwise the function will `POSIX_BAIL` with `S2N_ERR_NULL`
309 : : */
310 : 995105826 : #define POSIX_ENSURE_REF(x) __S2N_ENSURE(S2N_OBJECT_PTR_IS_READABLE(x), POSIX_BAIL(S2N_ERR_NULL))
311 : :
312 : : /**
313 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
314 : : *
315 : : * Ensures `x` is a mutable reference, otherwise the function will `POSIX_BAIL` with `S2N_ERR_NULL`
316 : : */
317 : 20535734 : #define POSIX_ENSURE_MUT(x) __S2N_ENSURE(S2N_OBJECT_PTR_IS_WRITABLE(x), POSIX_BAIL(S2N_ERR_NULL))
318 : :
319 : : /**
320 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
321 : : *
322 : : * Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal
323 : : *
324 : : * `POSIX_PRECONDITION` should be used at the beginning of a function to make assertions about
325 : : * the provided arguments. By default, it is functionally equivalent to `POSIX_GUARD_RESULT(result)`
326 : : * but can be altered by a testing environment to provide additional guarantees.
327 : : */
328 : 624318263 : #define POSIX_PRECONDITION(result) POSIX_GUARD_RESULT(__S2N_ENSURE_PRECONDITION((result)))
329 : :
330 : : /**
331 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
332 : : *
333 : : * Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal
334 : : *
335 : : * NOTE: The condition will _only_ be checked when the code is compiled in debug mode.
336 : : * In release mode, the check is removed.
337 : : *
338 : : * `POSIX_POSTCONDITION` should be used at the end of a function to make assertions about
339 : : * the resulting state. In debug mode, it is functionally equivalent to `POSIX_GUARD_RESULT(result)`.
340 : : * In production builds, it becomes a no-op. This can also be altered by a testing environment
341 : : * to provide additional guarantees.
342 : : */
343 : 422565378 : #define POSIX_POSTCONDITION(result) POSIX_GUARD_RESULT(__S2N_ENSURE_POSTCONDITION((result)))
344 : :
345 : : /**
346 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
347 : : *
348 : : * Performs a safer memcpy.
349 : : *
350 : : * The following checks are performed:
351 : : *
352 : : * * `destination` is non-null
353 : : * * `source` is non-null
354 : : *
355 : : * Callers will still need to ensure the following:
356 : : *
357 : : * * The size of the data pointed to by both the `destination` and `source` parameters,
358 : : * shall be at least `len` bytes.
359 : : */
360 : 127564722 : #define POSIX_CHECKED_MEMCPY(destination, source, len) __S2N_ENSURE_SAFE_MEMMOVE((destination), (source), (len), POSIX_ENSURE_REF)
361 : :
362 : : /**
363 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
364 : : *
365 : : * Performs a safer memset
366 : : *
367 : : * The following checks are performed:
368 : : *
369 : : * * `destination` is non-null
370 : : *
371 : : * Callers will still need to ensure the following:
372 : : *
373 : : * * The size of the data pointed to by the `destination` parameter shall be at least
374 : : * `len` bytes.
375 : : */
376 : 116957159 : #define POSIX_CHECKED_MEMSET(destination, value, len) __S2N_ENSURE_SAFE_MEMSET((destination), (value), (len), POSIX_ENSURE_REF)
377 : :
378 : : /**
379 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
380 : : *
381 : : * Ensures `(result) > S2N_FAILURE`, otherwise the function will return `S2N_FAILURE`
382 : : */
383 : 1107988025 : #define POSIX_GUARD(result) __S2N_ENSURE((result) > S2N_FAILURE, __S2N_ENSURE_CHECKED_RETURN(S2N_FAILURE))
384 : :
385 : : /**
386 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
387 : : *
388 : : * Ensures `result == _OSSL_SUCCESS`, otherwise the function will `POSIX_BAIL` with `error`
389 : : */
390 : 85388879 : #define POSIX_GUARD_OSSL(result, error) __S2N_ENSURE((result) == _OSSL_SUCCESS, POSIX_BAIL(error))
391 : :
392 : : /**
393 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
394 : : *
395 : : * Ensures `s2n_result_is_ok(result)`, otherwise the function will return `S2N_FAILURE`
396 : : */
397 : 1101847200 : #define POSIX_GUARD_RESULT(result) __S2N_ENSURE(s2n_result_is_ok(result), __S2N_ENSURE_CHECKED_RETURN(S2N_FAILURE))
398 : :
399 : : /**
400 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
401 : : *
402 : : * Ensures `(result) != NULL`, otherwise the function will return `S2N_FAILURE`
403 : : *
404 : : * Does not set s2n_errno to S2N_ERR_NULL, so is NOT a direct replacement for POSIX_ENSURE_REF.
405 : : */
406 : 8194 : #define POSIX_GUARD_PTR(result) __S2N_ENSURE((result) != NULL, __S2N_ENSURE_CHECKED_RETURN(S2N_FAILURE))
407 : :
408 : : /**
409 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
410 : : *
411 : : * Sets the global `s2n_errno` to `error` and returns with an `NULL`
412 : : */
413 : 7 : #define PTR_BAIL(error) do { _S2N_ERROR((error)); __S2N_ENSURE_CHECKED_RETURN(NULL); } while (0)
414 : :
415 : : /**
416 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
417 : : *
418 : : * Ensures the `condition` is `true`, otherwise the function will `PTR_BAIL` with `error`
419 : : */
420 : 2662 : #define PTR_ENSURE(condition, error) __S2N_ENSURE((condition), PTR_BAIL(error))
421 : :
422 : : /**
423 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
424 : : *
425 : : * Ensures the `condition` is `true`, otherwise the function will `PTR_BAIL` with `error`
426 : : *
427 : : * NOTE: The condition will _only_ be checked when the code is compiled in debug mode.
428 : : * In release mode, the check is removed.
429 : : */
430 : : #define PTR_DEBUG_ENSURE(condition, error) __S2N_ENSURE_DEBUG((condition), PTR_BAIL(error))
431 : :
432 : : /**
433 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
434 : : *
435 : : * Ensures `(result) != NULL`, otherwise the function will `PTR_BAIL` with `error`
436 : : *
437 : : * This can be useful for overriding the global `s2n_errno`
438 : : */
439 : : #define PTR_ENSURE_OK(result, error) __S2N_ENSURE((result) != NULL, PTR_BAIL(error))
440 : :
441 : : /**
442 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
443 : : *
444 : : * Ensures `a` is greater than or equal to `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error
445 : : */
446 : 25709225 : #define PTR_ENSURE_GTE(a, b) __S2N_ENSURE((a) >= (b), PTR_BAIL(S2N_ERR_SAFETY))
447 : :
448 : : /**
449 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
450 : : *
451 : : * Ensures `a` is less than or equal to `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error
452 : : */
453 : : #define PTR_ENSURE_LTE(a, b) __S2N_ENSURE((a) <= (b), PTR_BAIL(S2N_ERR_SAFETY))
454 : :
455 : : /**
456 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
457 : : *
458 : : * Ensures `a` is greater than `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error
459 : : */
460 : : #define PTR_ENSURE_GT(a, b) __S2N_ENSURE((a) > (b), PTR_BAIL(S2N_ERR_SAFETY))
461 : :
462 : : /**
463 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
464 : : *
465 : : * Ensures `a` is less than `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error
466 : : */
467 : 25709225 : #define PTR_ENSURE_LT(a, b) __S2N_ENSURE((a) < (b), PTR_BAIL(S2N_ERR_SAFETY))
468 : :
469 : : /**
470 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
471 : : *
472 : : * Ensures `a` is equal to `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error
473 : : */
474 : : #define PTR_ENSURE_EQ(a, b) __S2N_ENSURE((a) == (b), PTR_BAIL(S2N_ERR_SAFETY))
475 : :
476 : : /**
477 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
478 : : *
479 : : * Ensures `a` is not equal to `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error
480 : : */
481 : : #define PTR_ENSURE_NE(a, b) __S2N_ENSURE((a) != (b), PTR_BAIL(S2N_ERR_SAFETY))
482 : :
483 : : /**
484 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
485 : : *
486 : : * Ensures `min <= n <= max`, otherwise the function will `PTR_BAIL` with `S2N_ERR_SAFETY`
487 : : */
488 : : #define PTR_ENSURE_INCLUSIVE_RANGE(min, n, max) \
489 : : do { \
490 : : __typeof(n) __tmp_n = ( n ); \
491 : : __typeof(n) __tmp_min = ( min ); \
492 : : __typeof(n) __tmp_max = ( max ); \
493 : : PTR_ENSURE_GTE(__tmp_n, __tmp_min); \
494 : : PTR_ENSURE_LTE(__tmp_n, __tmp_max); \
495 : : } while(0)
496 : :
497 : : /**
498 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
499 : : *
500 : : * Ensures `min < n < max`, otherwise the function will `PTR_BAIL` with `S2N_ERR_SAFETY`
501 : : */
502 : : #define PTR_ENSURE_EXCLUSIVE_RANGE(min, n, max) \
503 : : do { \
504 : : __typeof(n) __tmp_n = ( n ); \
505 : : __typeof(n) __tmp_min = ( min ); \
506 : : __typeof(n) __tmp_max = ( max ); \
507 : : PTR_ENSURE_GT(__tmp_n, __tmp_min); \
508 : : PTR_ENSURE_LT(__tmp_n, __tmp_max); \
509 : : } while(0)
510 : :
511 : : /**
512 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
513 : : *
514 : : * Ensures `x` is a readable reference, otherwise the function will `PTR_BAIL` with `S2N_ERR_NULL`
515 : : */
516 : 355436524 : #define PTR_ENSURE_REF(x) __S2N_ENSURE(S2N_OBJECT_PTR_IS_READABLE(x), PTR_BAIL(S2N_ERR_NULL))
517 : :
518 : : /**
519 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
520 : : *
521 : : * Ensures `x` is a mutable reference, otherwise the function will `PTR_BAIL` with `S2N_ERR_NULL`
522 : : */
523 : : #define PTR_ENSURE_MUT(x) __S2N_ENSURE(S2N_OBJECT_PTR_IS_WRITABLE(x), PTR_BAIL(S2N_ERR_NULL))
524 : :
525 : : /**
526 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
527 : : *
528 : : * Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal
529 : : *
530 : : * `PTR_PRECONDITION` should be used at the beginning of a function to make assertions about
531 : : * the provided arguments. By default, it is functionally equivalent to `PTR_GUARD_RESULT(result)`
532 : : * but can be altered by a testing environment to provide additional guarantees.
533 : : */
534 : 3861 : #define PTR_PRECONDITION(result) PTR_GUARD_RESULT(__S2N_ENSURE_PRECONDITION((result)))
535 : :
536 : : /**
537 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
538 : : *
539 : : * Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal
540 : : *
541 : : * NOTE: The condition will _only_ be checked when the code is compiled in debug mode.
542 : : * In release mode, the check is removed.
543 : : *
544 : : * `PTR_POSTCONDITION` should be used at the end of a function to make assertions about
545 : : * the resulting state. In debug mode, it is functionally equivalent to `PTR_GUARD_RESULT(result)`.
546 : : * In production builds, it becomes a no-op. This can also be altered by a testing environment
547 : : * to provide additional guarantees.
548 : : */
549 : : #define PTR_POSTCONDITION(result) PTR_GUARD_RESULT(__S2N_ENSURE_POSTCONDITION((result)))
550 : :
551 : : /**
552 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
553 : : *
554 : : * Performs a safer memcpy.
555 : : *
556 : : * The following checks are performed:
557 : : *
558 : : * * `destination` is non-null
559 : : * * `source` is non-null
560 : : *
561 : : * Callers will still need to ensure the following:
562 : : *
563 : : * * The size of the data pointed to by both the `destination` and `source` parameters,
564 : : * shall be at least `len` bytes.
565 : : */
566 : 366 : #define PTR_CHECKED_MEMCPY(destination, source, len) __S2N_ENSURE_SAFE_MEMMOVE((destination), (source), (len), PTR_ENSURE_REF)
567 : :
568 : : /**
569 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
570 : : *
571 : : * Performs a safer memset
572 : : *
573 : : * The following checks are performed:
574 : : *
575 : : * * `destination` is non-null
576 : : *
577 : : * Callers will still need to ensure the following:
578 : : *
579 : : * * The size of the data pointed to by the `destination` parameter shall be at least
580 : : * `len` bytes.
581 : : */
582 : : #define PTR_CHECKED_MEMSET(destination, value, len) __S2N_ENSURE_SAFE_MEMSET((destination), (value), (len), PTR_ENSURE_REF)
583 : :
584 : : /**
585 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
586 : : *
587 : : * Ensures `(result) != NULL`, otherwise the function will return `NULL`
588 : : */
589 : : #define PTR_GUARD(result) __S2N_ENSURE((result) != NULL, __S2N_ENSURE_CHECKED_RETURN(NULL))
590 : :
591 : : /**
592 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
593 : : *
594 : : * Ensures `result == _OSSL_SUCCESS`, otherwise the function will `PTR_BAIL` with `error`
595 : : */
596 : : #define PTR_GUARD_OSSL(result, error) __S2N_ENSURE((result) == _OSSL_SUCCESS, PTR_BAIL(error))
597 : :
598 : : /**
599 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
600 : : *
601 : : * Ensures `s2n_result_is_ok(result)`, otherwise the function will return `NULL`
602 : : */
603 : 386890 : #define PTR_GUARD_RESULT(result) __S2N_ENSURE(s2n_result_is_ok(result), __S2N_ENSURE_CHECKED_RETURN(NULL))
604 : :
605 : : /**
606 : : * DEPRECATED: all methods (except those in s2n.h) should return s2n_result.
607 : : *
608 : : * Ensures `(result) > S2N_FAILURE`, otherwise the function will return `NULL`
609 : : */
610 : 13956318 : #define PTR_GUARD_POSIX(result) __S2N_ENSURE((result) > S2N_FAILURE, __S2N_ENSURE_CHECKED_RETURN(NULL))
611 : :
|
