1 | /* |
2 | * Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved. |
3 | * |
4 | * Licensed under the Apache License 2.0 (the "License"). You may not use |
5 | * this file except in compliance with the License. You can obtain a copy |
6 | * in the file LICENSE in the source distribution or at |
7 | * https://www.openssl.org/source/license.html |
8 | */ |
9 | |
10 | #include <openssl/crypto.h> |
11 | |
12 | /* |
13 | * Initialisation of global data should never happen via "RUN_ONCE" inside the |
14 | * FIPS module. Global data should instead always be associated with a specific |
15 | * OPENSSL_CTX object. In this way data will get cleaned up correctly when the |
16 | * module gets unloaded. |
17 | */ |
18 | #if !defined(FIPS_MODE) || defined(ALLOW_RUN_ONCE_IN_FIPS) |
19 | /* |
20 | * DEFINE_RUN_ONCE: Define an initialiser function that should be run exactly |
21 | * once. It takes no arguments and returns and int result (1 for success or |
22 | * 0 for failure). Typical usage might be: |
23 | * |
24 | * DEFINE_RUN_ONCE(myinitfunc) |
25 | * { |
26 | * do_some_initialisation(); |
27 | * if (init_is_successful()) |
28 | * return 1; |
29 | * |
30 | * return 0; |
31 | * } |
32 | */ |
33 | # define DEFINE_RUN_ONCE(init) \ |
34 | static int init(void); \ |
35 | int init##_ossl_ret_ = 0; \ |
36 | void init##_ossl_(void) \ |
37 | { \ |
38 | init##_ossl_ret_ = init(); \ |
39 | } \ |
40 | static int init(void) |
41 | |
42 | /* |
43 | * DECLARE_RUN_ONCE: Declare an initialiser function that should be run exactly |
44 | * once that has been defined in another file via DEFINE_RUN_ONCE(). |
45 | */ |
46 | # define DECLARE_RUN_ONCE(init) \ |
47 | extern int init##_ossl_ret_; \ |
48 | void init##_ossl_(void); |
49 | |
50 | /* |
51 | * DEFINE_RUN_ONCE_STATIC: Define an initialiser function that should be run |
52 | * exactly once. This function will be declared as static within the file. It |
53 | * takes no arguments and returns and int result (1 for success or 0 for |
54 | * failure). Typical usage might be: |
55 | * |
56 | * DEFINE_RUN_ONCE_STATIC(myinitfunc) |
57 | * { |
58 | * do_some_initialisation(); |
59 | * if (init_is_successful()) |
60 | * return 1; |
61 | * |
62 | * return 0; |
63 | * } |
64 | */ |
65 | # define DEFINE_RUN_ONCE_STATIC(init) \ |
66 | static int init(void); \ |
67 | static int init##_ossl_ret_ = 0; \ |
68 | static void init##_ossl_(void) \ |
69 | { \ |
70 | init##_ossl_ret_ = init(); \ |
71 | } \ |
72 | static int init(void) |
73 | |
74 | /* |
75 | * DEFINE_RUN_ONCE_STATIC_ALT: Define an alternative initialiser function. This |
76 | * function will be declared as static within the file. It takes no arguments |
77 | * and returns and int result (1 for success or 0 for failure). An alternative |
78 | * initialiser function is expected to be associated with a primary initialiser |
79 | * function defined via DEFINE_ONCE_STATIC where both functions use the same |
80 | * CRYPTO_ONCE object to synchronise. Where an alternative initialiser function |
81 | * is used only one of the primary or the alternative initialiser function will |
82 | * ever be called - and that function will be called exactly once. Definition |
83 | * of an alternative initialiser function MUST occur AFTER the definition of the |
84 | * primary initialiser function. |
85 | * |
86 | * Typical usage might be: |
87 | * |
88 | * DEFINE_RUN_ONCE_STATIC(myinitfunc) |
89 | * { |
90 | * do_some_initialisation(); |
91 | * if (init_is_successful()) |
92 | * return 1; |
93 | * |
94 | * return 0; |
95 | * } |
96 | * |
97 | * DEFINE_RUN_ONCE_STATIC_ALT(myaltinitfunc, myinitfunc) |
98 | * { |
99 | * do_some_alternative_initialisation(); |
100 | * if (init_is_successful()) |
101 | * return 1; |
102 | * |
103 | * return 0; |
104 | * } |
105 | */ |
106 | # define DEFINE_RUN_ONCE_STATIC_ALT(initalt, init) \ |
107 | static int initalt(void); \ |
108 | static void initalt##_ossl_(void) \ |
109 | { \ |
110 | init##_ossl_ret_ = initalt(); \ |
111 | } \ |
112 | static int initalt(void) |
113 | |
114 | /* |
115 | * RUN_ONCE - use CRYPTO_THREAD_run_once, and check if the init succeeded |
116 | * @once: pointer to static object of type CRYPTO_ONCE |
117 | * @init: function name that was previously given to DEFINE_RUN_ONCE, |
118 | * DEFINE_RUN_ONCE_STATIC or DECLARE_RUN_ONCE. This function |
119 | * must return 1 for success or 0 for failure. |
120 | * |
121 | * The return value is 1 on success (*) or 0 in case of error. |
122 | * |
123 | * (*) by convention, since the init function must return 1 on success. |
124 | */ |
125 | # define RUN_ONCE(once, init) \ |
126 | (CRYPTO_THREAD_run_once(once, init##_ossl_) ? init##_ossl_ret_ : 0) |
127 | |
128 | /* |
129 | * RUN_ONCE_ALT - use CRYPTO_THREAD_run_once, to run an alternative initialiser |
130 | * function and check if that initialisation succeeded |
131 | * @once: pointer to static object of type CRYPTO_ONCE |
132 | * @initalt: alternative initialiser function name that was previously given to |
133 | * DEFINE_RUN_ONCE_STATIC_ALT. This function must return 1 for |
134 | * success or 0 for failure. |
135 | * @init: primary initialiser function name that was previously given to |
136 | * DEFINE_RUN_ONCE_STATIC. This function must return 1 for success or |
137 | * 0 for failure. |
138 | * |
139 | * The return value is 1 on success (*) or 0 in case of error. |
140 | * |
141 | * (*) by convention, since the init function must return 1 on success. |
142 | */ |
143 | # define RUN_ONCE_ALT(once, initalt, init) \ |
144 | (CRYPTO_THREAD_run_once(once, initalt##_ossl_) ? init##_ossl_ret_ : 0) |
145 | |
146 | #endif /* FIPS_MODE */ |
147 | |