Support for flow protected functions. More...
Macros | |
#define | MCUX_CSSL_FP_PROTECTED_TYPE(resultType) |
Based on a given base type, builds a return type with flow protection. | |
#define | MCUX_CSSL_FP_COUNTER_STMT(statement) |
A statement which is only evaluated if a secure counter is used. | |
#define | MCUX_CSSL_FP_FUNCTION_DECL(...) |
Declaration of a flow protected function. | |
#define | MCUX_CSSL_FP_FUNCTION_DEF(...) |
Definition of a flow protected function. | |
#define | MCUX_CSSL_FP_FUNCTION_POINTER(type, definition) |
Definition of a flow protected function pointer. | |
#define | MCUX_CSSL_FP_FUNCTION_ENTRY(...) |
Flow protection handler for the function entry point. | |
#define | MCUX_CSSL_FP_FUNCTION_EXIT(...) |
Flow protection handler for the function exit point. | |
#define | MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK(...) |
Flow protection handler for the function exit point which includes an actual check of the code flow. | |
#define | MCUX_CSSL_FP_FUNCTION_EXIT_VOID(...) |
Flow protection handler for the exit point of functions with the return type void . | |
#define | MCUX_CSSL_FP_RESULT(...) |
Extract the result value from a protected return value. | |
#define | MCUX_CSSL_FP_PROTECTION_TOKEN(return) |
Extract the protection token value from a protected return value. | |
#define | MCUX_CSSL_FP_FUNCTION_CALL(...) |
Call a flow protected function. | |
#define | MCUX_CSSL_FP_FUNCTION_CALL_VOID(...) |
Call a flow protected void function. | |
#define | MCUX_CSSL_FP_FUNCTION_CALL_PROTECTED(...) |
Call a flow protected function from unprotected code. | |
#define | MCUX_CSSL_FP_FUNCTION_CALL_VOID_PROTECTED(...) |
Call a flow protected void function from unprotected code. | |
#define | MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(...) |
Call a flow protected function and check the protection token. | |
#define | MCUX_CSSL_FP_FUNCTION_CALL_END(...) |
End a function call section started by MCUX_CSSL_FP_FUNCTION_CALL_BEGIN. | |
#define | MCUX_CSSL_FP_FUNCTION_CALL_VOID_BEGIN(...) |
Call a flow protected void function and check the protection token. | |
#define | MCUX_CSSL_FP_FUNCTION_CALL_VOID_END(...) |
End a void function call section started by MCUX_CSSL_FP_FUNCTION_CALL_VOID_BEGIN. | |
#define | MCUX_CSSL_FP_FUNCTION_CALLED(...) |
Expectation of a called function. | |
#define | MCUX_CSSL_FP_FUNCTION_ENTERED(id) |
Expectation implementation of an entered (but not exited) function. | |
Support for flow protected functions.
#define MCUX_CSSL_FP_PROTECTED_TYPE | ( | resultType | ) |
Based on a given base type, builds a return type with flow protection.
This macro must be used to wrap the function return type. For example:
Note that depending on the selected flow protection mechanism, the width of the result type may be limited to 32 bits or less to allow encoding a protection token in the other half of a 64-bit return value.
resultType | The type to be converted into a protected type. |
#define MCUX_CSSL_FP_COUNTER_STMT | ( | statement | ) |
A statement which is only evaluated if a secure counter is used.
This macro can be used to create counting variables that are only present if the active configuration uses a secure counter, to avoid warnings about unused variables.
statement | The statement to be conditionally included. |
#define MCUX_CSSL_FP_FUNCTION_DECL | ( | ... | ) |
Declaration of a flow protected function.
This declaration must be placed just in front of the actual function declaration. For example:
id | Identifier for the function that is flow protected. |
ptrType | Optional, pointer type matching this function. |
#define MCUX_CSSL_FP_FUNCTION_DEF | ( | ... | ) |
Definition of a flow protected function.
This definition macro must be placed just in front of the actual function definition, that has been previously declared as flow protected using MCUX_CSSL_FP_FUNCTION_DECL. For example:
id | Identifier for the function that is flow protected. |
ptrType | Optional, pointer type matching this function. |
#define MCUX_CSSL_FP_FUNCTION_POINTER | ( | type, | |
definition | |||
) |
Definition of a flow protected function pointer.
This definition macro must be placed around a function pointer definition. For example:
type | Identifier for the function pointer type that is flow protected. |
definition | Actual type definition of the function pointer type. |
#define MCUX_CSSL_FP_FUNCTION_ENTRY | ( | ... | ) |
Flow protection handler for the function entry point.
This entry macro should be placed at the start of the function body that needs to be protected. The function must have been declared before as flow protected using MCUX_CSSL_FP_FUNCTION_DECL. For example:
The only statements that should be placed before this one, are declarations for flow protected operations that are already used as expectations in this macro. For example:
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_FUNCTION_EXIT | ( | ... | ) |
Flow protection handler for the function exit point.
This exit macro must replace the regular return
statements of a protected function. Given the following unprotected example:
The protected version would become:
... | The following parameters need to be passed (comma separated):
|
result
and a flow protection token are encoded. #define MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK | ( | ... | ) |
Flow protection handler for the function exit point which includes an actual check of the code flow.
This exit macro must replace the regular return
statements of a protected function. In addition to MCUX_CSSL_FP_FUNCTION_EXIT it also checks the flow protection, and selects the return value accordingly. For example:
... | The following parameters need to be passed (comma separated):
|
pass
or fail
) and a flow protection token are encoded. #define MCUX_CSSL_FP_FUNCTION_EXIT_VOID | ( | ... | ) |
Flow protection handler for the exit point of functions with the return type void
.
This exit macro must replace the regular return
statements of a protected void function. Given the following unprotected example:
The protected version would become:
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_RESULT | ( | ... | ) |
Extract the result value from a protected return
value.
This macro should mainly be used internally to extract the original return value from a protected value, e.g., in MCUX_CSSL_FP_FUNCTION_CALL_IMPL.
... | The following parameters need to be passed (comma seperated):
|
#define MCUX_CSSL_FP_PROTECTION_TOKEN | ( | return | ) |
Extract the protection token value from a protected return
value.
Note that this macro is only used with a local security counter, e.g. for configuration CSSL_SC_USE_SW_LOCAL
return | The protected return value which contains the protection token. |
#define MCUX_CSSL_FP_FUNCTION_CALL | ( | ... | ) |
Call a flow protected function.
This function call macro encapsulates the flow protection handling needed for calling a function. In particular it takes care of extracting the flow protection token from the return value (which has been inserted by MCUX_CSSL_FP_FUNCTION_EXIT or MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK) and incorporating that in the flow protection of the current function. For example:
For functions returning void, the macro MCUX_CSSL_FP_FUNCTION_CALL_VOID exists.
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_FUNCTION_CALL_VOID | ( | ... | ) |
Call a flow protected void function.
This function call macro encapsulates the flow protection handling needed for calling a void function. In particular it takes care of extracting the flow protection token from the return value (which has been inserted by MCUX_CSSL_FP_FUNCTION_EXIT or MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK) and incorporating that in the flow protection of the current function. For example:
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_FUNCTION_CALL_PROTECTED | ( | ... | ) |
Call a flow protected function from unprotected code.
This function call macro encapsulates the flow protection handling needed for calling a function from within a function which does not have local flow protection, or which uses a different flow protection mechanism than the one provided by CSSL. In particular it takes care of extracting the protection token and result from the return value (which has been inserted by MCUX_CSSL_FP_FUNCTION_EXIT or MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK). For example:
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_FUNCTION_CALL_VOID_PROTECTED | ( | ... | ) |
Call a flow protected void function from unprotected code.
This function call macro encapsulates the flow protection handling needed for calling a void function from within a function which does not have flow protection, or which uses a different flow protection mechanism than the one provided by CSSL. In particular it takes care of extracting the protection token and result from the return value (which has been inserted by MCUX_CSSL_FP_FUNCTION_EXIT or MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK). For example:
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_FUNCTION_CALL_BEGIN | ( | ... | ) |
Call a flow protected function and check the protection token.
This function call macro encapsulates the flow protection handling needed for calling a function from within a function which does not have local flow protection, or which uses a different flow protection mechanism than the one provided by CSSL. In particular it takes care of extracting the protection token and result from the return value (which has been inserted by MCUX_CSSL_FP_FUNCTION_EXIT or MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK). For example:
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_FUNCTION_CALL_END | ( | ... | ) |
End a function call section started by MCUX_CSSL_FP_FUNCTION_CALL_BEGIN.
Example:
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_FUNCTION_CALL_VOID_BEGIN | ( | ... | ) |
Call a flow protected void function and check the protection token.
This function call macro encapsulates the flow protection handling needed for calling a void function from within a function which does not have local flow protection, or which uses a different flow protection mechanism than the one provided by CSSL. In particular it takes care of extracting the protection token from the return value (which has been inserted by MCUX_CSSL_FP_FUNCTION_EXIT or MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK). For example:
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_FUNCTION_CALL_VOID_END | ( | ... | ) |
End a void function call section started by MCUX_CSSL_FP_FUNCTION_CALL_VOID_BEGIN.
Example:
... | The following parameters need to be passed (comma separated):
|
#define MCUX_CSSL_FP_FUNCTION_CALLED | ( | ... | ) |
Expectation of a called function.
This expectation macro indicates to the flow protection mechanism that a function call is expected to happen (if placed before the actual call), for example:
Or that a function call has happened (if placed after the actual call), for example:
... | The following parameters need to be passed (comma separated): -id: Identifier of the function that is expected to be called. |
#define MCUX_CSSL_FP_FUNCTION_ENTERED | ( | id | ) |
Expectation implementation of an entered (but not exited) function.
This expectation macro indicates to the flow protection mechanism that a function entry has happened, for example:
id | Identifier of the function that is expected to be entered. |