1 /*--------------------------------------------------------------------------*/ 2 /* Copyright 2020-2021 NXP */ 3 /* */ 4 /* NXP Confidential. This software is owned or controlled by NXP and may */ 5 /* only be used strictly in accordance with the applicable license terms. */ 6 /* By expressly accepting such terms or by downloading, installing, */ 7 /* activating and/or otherwise using the software, you are agreeing that */ 8 /* you have read, and that you agree to comply with and are bound by, such */ 9 /* license terms. If you do not agree to be bound by the applicable license */ 10 /* terms, then you may not retain, install, activate or otherwise use the */ 11 /* software. */ 12 /*--------------------------------------------------------------------------*/ 13 14 /** 15 * \file mcuxCsslFlowProtection_SecureCounter_Local.h 16 * \brief Counter based implementation for the flow protection mechanism, for a local security counter. 17 */ 18 19 #ifndef MCUX_CSSL_FLOW_PROTECTION_SECURE_COUNTER_LOCAL_H_ 20 #define MCUX_CSSL_FLOW_PROTECTION_SECURE_COUNTER_LOCAL_H_ 21 22 /* Include the CSSL C pre-processor support functionality. */ 23 #include <internal/mcuxCsslCPreProcessor.h> 24 25 /* Include the CSSL secure counter mechanism as basic building block. */ 26 #include <mcuxCsslSecureCounter.h> 27 28 /* Include the function identifier definitions. */ 29 #include <mcuxCsslFlowProtection_FunctionIdentifiers.h> 30 31 /* Include the C99 standard integer types. */ 32 #include <stdint.h> 33 34 35 /** 36 * \def MCUX_CSSL_FP_PROTECTED_TYPE_IMPL 37 * \brief Based on a given base type, builds a return type with flow 38 * protection. 39 * \ingroup csslFpCntFunction 40 * 41 * \see MCUX_CSSL_FP_FUNCTION_DEF_IMPL 42 * 43 * \param resultType The type to be converted into a protected type. 44 */ 45 #define MCUX_CSSL_FP_PROTECTED_TYPE_IMPL(resultType) \ 46 uint64_t 47 48 /** 49 * \def MCUX_CSSL_FP_FUNCTION_ENTRY_IMPLn 50 * \brief Flow protection handler implementation for the function entry point. 51 * \ingroup csslFpCntFunction 52 * 53 * Initialize the counter with the entry part of the function identifier, and 54 * include expectations in the initialization value. 55 * 56 * \see MCUX_CSSL_FP_FUNCTION_ENTRY_IMPL 57 * 58 * \param id Identifier of the function that has just been entered. 59 * \param expect One or more (comma separated) declarations of expected code 60 * flow behavior. 61 */ 62 #define MCUX_CSSL_FP_FUNCTION_ENTRY_IMPLn(function, ...) \ 63 MCUX_CSSL_SC_INIT( \ 64 MCUX_CSSL_FP_FUNCTION_ID_ENTRY_PART(function) \ 65 - (MCUX_CSSL_FP_EXPECTATIONS(__VA_ARGS__)) \ 66 ) 67 68 /** 69 * \def MCUX_CSSL_FP_FUNCTION_ENTRY_IMPL1 70 * \brief Flow protection handler implementation for the function entry point. 71 * \ingroup csslFpCntFunction 72 * 73 * Initialize the counter with the entry part of the function identifier, 74 * without any potential expectations. 75 * 76 * \see MCUX_CSSL_FP_FUNCTION_ENTRY_IMPL 77 * 78 * \param id Identifier of the function that has just been entered. 79 */ 80 #define MCUX_CSSL_FP_FUNCTION_ENTRY_IMPL1(function) \ 81 MCUX_CSSL_FP_FUNCTION_ENTRY_IMPLn(function, 0u) 82 83 /** 84 * \def MCUX_CSSL_FP_FUNCTION_ENTRY_IMPL 85 * \brief Flow protection handler implementation for the function entry point. 86 * \ingroup csslFpCntFunction 87 * 88 * Initialize the counter with entry part of the function identifier, and 89 * include potential expectations in the initialization value. 90 * 91 * Implemented as an overloaded macro to simplify the use of the API. 92 * 93 * \see MCUX_CSSL_FP_FUNCTION_ENTRY_IMPL1 94 * \see MCUX_CSSL_FP_FUNCTION_ENTRY_IMPLn 95 * 96 * \param id Identifier of the function that has just been entered. 97 * \param expect Zero or more (comma separated) declarations of expected code 98 * flow behavior. 99 */ 100 #define MCUX_CSSL_FP_FUNCTION_ENTRY_IMPL(...) \ 101 MCUX_CSSL_CPP_OVERLOADED1(MCUX_CSSL_FP_FUNCTION_ENTRY_IMPL, __VA_ARGS__) 102 103 104 /** 105 * \def MCUX_CSSL_FP_FUNCTION_EXIT_IMPLn 106 * \brief Flow protection handler implementation for the function exit point. 107 * \ingroup csslFpCntFunction 108 * 109 * Adjust the counter with the exit part of the function identifier, and 110 * include potential expectations in the adjustment value. Return the counter 111 * value together with the \p result via the function return value. 112 * 113 * \see MCUX_CSSL_FP_FUNCTION_EXIT_IMPL 114 * 115 * \param id Identifier of the function from which we will exit. 116 * \param result Result that should be encoded in the return value. 117 * \param expect One or more (comma separated) declarations of expected code 118 * flow behavior. 119 * \return A value in which both \p result and a flow protection token 120 * are encoded. 121 */ 122 #define MCUX_CSSL_FP_FUNCTION_EXIT_IMPLn(id, result, ...) \ 123 MCUX_CSSL_SC_ADD( \ 124 MCUX_CSSL_FP_FUNCTION_ID_EXIT_PART(id) \ 125 - MCUX_CSSL_FP_EXPECTATIONS(__VA_ARGS__) \ 126 ); \ 127 return (MCUX_CSSL_FP_RESULT_VALUE(result) \ 128 | MCUX_CSSL_FP_PROTECTION_TOKEN_VALUE(MCUX_CSSL_FP_COUNTER_COMPRESSED())) 129 130 /** 131 * \def MCUX_CSSL_FP_FUNCTION_EXIT_IMPL1 132 * \brief Flow protection handler implementation for the function exit point. 133 * \ingroup csslFpCntFunction 134 * 135 * Adjust the counter with the exit part of the function identifier, without 136 * any potential expectations in the adjustment value. Return the counter value 137 * via the function return value. 138 * 139 * \see MCUX_CSSL_FP_FUNCTION_EXIT_IMPL 140 * 141 * \param id Identifier of the function from which we will exit. 142 * \return A value in which a flow protection token is encoded. 143 */ 144 #define MCUX_CSSL_FP_FUNCTION_EXIT_IMPL1(id) \ 145 MCUX_CSSL_FP_FUNCTION_EXIT_IMPLn(id, 0u, 0u) 146 147 /** 148 * \def MCUX_CSSL_FP_FUNCTION_EXIT_IMPL2 149 * \brief Flow protection handler implementation for the function exit point. 150 * \ingroup csslFpCntFunction 151 * 152 * Adjust the counter with the exit part of the function identifier, without 153 * any potential expectations in the adjustment value. Return the counter value 154 * together with the \p result via the function return value. 155 * 156 * \see MCUX_CSSL_FP_FUNCTION_EXIT_IMPL 157 * 158 * \param id Identifier of the function from which we will exit. 159 * \param result Result that should be encoded in the return value. 160 * \return A value in which both \p result and a flow protection token 161 * are encoded. 162 */ 163 #define MCUX_CSSL_FP_FUNCTION_EXIT_IMPL2(id, result) \ 164 MCUX_CSSL_FP_FUNCTION_EXIT_IMPLn(id, result, 0u) 165 166 /** 167 * \def MCUX_CSSL_FP_FUNCTION_EXIT_IMPL 168 * \brief Flow protection handler implementation for the function exit point. 169 * \ingroup csslFpCntFunction 170 * 171 * Adjust the counter with the exit part of the function identifier, and 172 * include potential expectations in the adjustment value. Return the counter 173 * value together with the \p result via the function return value. 174 * 175 * Implemented as an overloaded macro to simplify the use of the API. 176 * 177 * \see MCUX_CSSL_FP_FUNCTION_EXIT_IMPL1 178 * \see MCUX_CSSL_FP_FUNCTION_EXIT_IMPL2 179 * \see MCUX_CSSL_FP_FUNCTION_EXIT_IMPLn 180 * 181 * \param id Identifier of the function from which we will exit. 182 * \param result Result that should be encoded in the return value. 183 * \param expect Zero or more (comma separated) declarations of expected code 184 * flow behavior. 185 * \return A value in which both \p result and a flow protection token 186 * are encoded. 187 */ 188 #define MCUX_CSSL_FP_FUNCTION_EXIT_IMPL(...) \ 189 MCUX_CSSL_CPP_OVERLOADED2(MCUX_CSSL_FP_FUNCTION_EXIT_IMPL, __VA_ARGS__) 190 191 /** 192 * \def MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPLn 193 * \brief Flow protection handler implementation for the function exit point 194 * which includes an actual check of the code flow. 195 * \ingroup csslFpCntFunction 196 * 197 * Adjust the counter with the exit part of the function identifier, and 198 * include potential expectations in the adjustment value. Check whether the 199 * counter matches the expected value, and choose the result from \p pass and 200 * \p fail and return it together with the counter value via the function 201 * return value. 202 * 203 * \see MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPL3 204 * \see MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPLn 205 * 206 * \param id Identifier of the function from which we will exit. 207 * \param pass Result that should be encoded in the return value if the flow 208 * protection check passed. 209 * \param fail Result that should be encoded in the return value if the flow 210 * protection check failed. 211 * \param expect One or more (comma separated) declarations of expected code 212 * flow behavior. 213 * \return A value in which both the result (either \p pass or \p fail) 214 * and a flow protection token are encoded. 215 */ 216 #define MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPLn(id, pass, fail, ...) \ 217 MCUX_CSSL_SC_ADD( \ 218 MCUX_CSSL_FP_FUNCTION_ID_EXIT_PART(id) \ 219 - MCUX_CSSL_FP_EXPECTATIONS(__VA_ARGS__) \ 220 ); \ 221 return (MCUX_CSSL_FP_RESULT_VALUE( \ 222 (MCUX_CSSL_SC_CHECK_PASSED == \ 223 MCUX_CSSL_SC_CHECK(MCUX_CSSL_FP_FUNCTION_VALUE(id))) \ 224 ? pass : fail) \ 225 | MCUX_CSSL_FP_PROTECTION_TOKEN_VALUE(MCUX_CSSL_FP_COUNTER_COMPRESSED())) 226 227 /** 228 * \def MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPL3 229 * \brief Flow protection handler implementation for the function exit point 230 * which includes an actual check of the code flow. 231 * \ingroup csslFpCntFunction 232 * 233 * Adjust the counter with the exit part of the function identifier. Check 234 * whether the counter matches the expected value, and choose the result from 235 * \p pass and \p fail and return it together with the counter value via the 236 * function return value. 237 * 238 * \see MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPL 239 * 240 * \param id Identifier of the function from which we will exit. 241 * \param pass Result that should be encoded in the return value if the flow 242 * protection check passed. 243 * \param fail Result that should be encoded in the return value if the flow 244 * protection check failed. 245 * \return A value in which both the result (either \p pass or \p fail) 246 * and a flow protection token are encoded. 247 */ 248 #define MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPL3(id, pass, fail) \ 249 MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPLn(id, pass, fail, 0u) 250 251 /** 252 * \def MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPL 253 * \brief Flow protection handler implementation for the function exit point 254 * which includes an actual check of the code flow. 255 * \ingroup csslFpCntFunction 256 * 257 * Adjust the counter with the exit part of the function identifier, and 258 * include potential expectations in the adjustment value. Check whether the 259 * counter matches the expected value, and choose the result from \p pass and 260 * \p fail and return it together with the counter value via the function 261 * return value. 262 * 263 * Implemented as an overloaded macro to simplify the use of the API. 264 * 265 * \see MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPL3 266 * \see MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPLn 267 * 268 * \param id Identifier of the function from which we will exit. 269 * \param pass Result that should be encoded in the return value if the flow 270 * protection check passed. 271 * \param fail Result that should be encoded in the return value if the flow 272 * protection check failed. 273 * \param expect Zero or more (comma separated) declarations of expected code 274 * flow behavior. 275 * \return A value in which both the result (either \p pass or \p fail) 276 * and a flow protection token are encoded. 277 */ 278 #define MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPL(...) \ 279 MCUX_CSSL_CPP_OVERLOADED3(MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK_IMPL, __VA_ARGS__) 280 281 /** 282 * \def MCUX_CSSL_FP_FUNCTION_EXIT_VOID_IMPL1 283 * \brief Flow protection handler for the exit point of functions with the 284 * return type \c void. 285 * \ingroup csslFpCntFunction 286 * 287 * \param id Identifier of the function from which we will exit. 288 * \return A protected return value of type void. 289 */ 290 #define MCUX_CSSL_FP_FUNCTION_EXIT_VOID_IMPL1(id) \ 291 MCUX_CSSL_FP_FUNCTION_EXIT_IMPL(id, 0U) 292 293 /** 294 * \def MCUX_CSSL_FP_FUNCTION_EXIT_VOID_IMPL2 295 * \brief Flow protection handler for the exit point of functions with the 296 * return type \c void. 297 * \ingroup csslFpCntFunction 298 * 299 * \param id Identifier of the function from which we will exit. 300 * \param expect One or more (comma separated) declarations of expected code 301 * flow behavior. 302 * \return A protected return value of type void. 303 */ 304 #define MCUX_CSSL_FP_FUNCTION_EXIT_VOID_IMPLn(id, ...) \ 305 MCUX_CSSL_FP_FUNCTION_EXIT_IMPL(id, 0U, __VA_ARGS__) 306 307 /** 308 * \def MCUX_CSSL_FP_FUNCTION_EXIT_VOID_IMPL 309 * \brief Flow protection handler for the exit point of functions with the 310 * return type \c void. 311 * \ingroup csslFpCntFunction 312 * 313 * \param id Identifier of the function from which we will exit. 314 * \param expect Zero or more (comma separated) declarations of expected code 315 * flow behavior. 316 * \return A protected return value of type void. 317 */ 318 #define MCUX_CSSL_FP_FUNCTION_EXIT_VOID_IMPL(...) \ 319 MCUX_CSSL_CPP_OVERLOADED1(MCUX_CSSL_FP_FUNCTION_EXIT_VOID_IMPL, __VA_ARGS__) 320 321 /** 322 * \def MCUX_CSSL_FP_FUNCTION_CALL_IMPL 323 * \brief Event implementation of a flow protected function call. 324 * \ingroup csslFpCntFunction 325 * 326 * 327 * \declaration{MCUX_CSSL_FP_FUNCTION_DECL_IMPL} 328 * \expectation{MCUX_CSSL_FP_FUNCTION_CALLED_IMPL} 329 * 330 * \param result Fresh variable name to store the result of \p call. 331 * \param call The (protected) function call that must be performed. 332 */ 333 #define MCUX_CSSL_FP_FUNCTION_CALL_IMPL(result, call) \ 334 const uint64_t MCUX_CSSL_CPP_CAT(result, _protected) = (call); \ 335 MCUX_CSSL_SC_ADD( \ 336 MCUX_CSSL_FP_PROTECTION_TOKEN(MCUX_CSSL_CPP_CAT(result, _protected))); \ 337 const uint32_t result = MCUX_CSSL_FP_RESULT( \ 338 MCUX_CSSL_CPP_CAT(result, _protected)) 339 340 /** 341 * \def MCUX_CSSL_FP_FUNCTION_CALL_VOID_IMPL 342 * \brief Event implementation of a flow protected void function call. 343 * \ingroup csslFpNoneFunction 344 * 345 * \declaration{MCUX_CSSL_FP_FUNCTION_DECL_IMPL} 346 * \expectation{MCUX_CSSL_FP_FUNCTION_CALLED_IMPL} 347 * 348 * \param call The (protected) function call that must be performed. 349 */ 350 #define MCUX_CSSL_FP_FUNCTION_CALL_VOID_IMPL(call) \ 351 { \ 352 const uint64_t MCUX_CSSL_CPP_CAT(result, _protected) = (call); \ 353 MCUX_CSSL_SC_ADD( \ 354 MCUX_CSSL_FP_PROTECTION_TOKEN(MCUX_CSSL_CPP_CAT(result, _protected))); \ 355 } 356 357 /** 358 * \def MCUX_CSSL_FP_FUNCTION_CALL_PROTECTED_IMPL 359 * \brief Implementation of a flow protected function call meant to be used 360 * from within an unprotected function 361 * \ingroup csslFpCntFunction 362 * 363 * 364 * \param result Fresh variable name to store the result of \p call. 365 * \param token Fresh variable name to store the protection token of \p call. 366 * \param call The (protected) function call that must be performed. 367 */ 368 #define MCUX_CSSL_FP_FUNCTION_CALL_PROTECTED_IMPL(result, token, call) \ 369 const uint64_t MCUX_CSSL_CPP_CAT(result, _protected) = (call); \ 370 const uint32_t token = MCUX_CSSL_FP_PROTECTION_TOKEN( \ 371 MCUX_CSSL_CPP_CAT(result, _protected)); \ 372 const uint32_t result = MCUX_CSSL_FP_RESULT( \ 373 MCUX_CSSL_CPP_CAT(result, _protected)) 374 375 /** 376 * \def MCUX_CSSL_FP_FUNCTION_CALL_VOID_PROTECTED_IMPL 377 * \brief Implementation of a flow protected void function call meant to be 378 * used from within an unprotected function 379 * \ingroup csslFpCntFunction 380 * 381 * 382 * \param token Fresh variable name to store the protection token of \p call. 383 * \param call The (protected) function call that must be performed. 384 */ 385 #define MCUX_CSSL_FP_FUNCTION_CALL_VOID_PROTECTED_IMPL(token, call) \ 386 const uint64_t MCUX_CSSL_CPP_CAT(token, _protected) = (call); \ 387 const uint32_t token = MCUX_CSSL_FP_PROTECTION_TOKEN( \ 388 MCUX_CSSL_CPP_CAT(token, _protected)); 389 390 /** 391 * \def MCUX_CSSL_FP_FUNCTION_CALL_BEGIN_IMPL 392 * \brief Implementation of a flow protected function call meant to be used 393 * from within an unprotected function, that must be terminated by 394 * #MCUX_CSSL_FP_FUNCTION_CALL_END_IMPL. 395 * \ingroup csslFpCntFunction 396 * 397 * 398 * \param result Fresh variable name to store the result of \p call. 399 * \param token Fresh variable name to store the protection token of \p call. 400 * \param call The (protected) function call that must be performed. 401 */ 402 #define MCUX_CSSL_FP_FUNCTION_CALL_BEGIN_IMPL(result, token, call) \ 403 { \ 404 MCUX_CSSL_FP_FUNCTION_CALL_PROTECTED_IMPL(result, token, call) 405 406 /** 407 * \def MCUX_CSSL_FP_FUNCTION_CALL_END_IMPL 408 * \brief Implementation of the end of a section started by 409 * #MCUX_CSSL_FP_FUNCTION_CALL_BEGIN_IMPL. 410 * \ingroup csslFpCntFunction 411 */ 412 #define MCUX_CSSL_FP_FUNCTION_CALL_END_IMPL() \ 413 } 414 415 416 #endif /* MCUX_CSSL_FLOW_PROTECTION_SECURE_COUNTER_LOCAL_H_ */ 417
