MCUX CLNS MCUX Crypto Library Normal Secure |

Macros
Function calling flow protection
MCUX CSSL &ndash; API » Flow Protection API

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. More...
#define | MCUX_CSSL_FP_COUNTER_STMT(statement)
| A statement which is only evaluated if a secure counter is used. More...
#define | MCUX_CSSL_FP_FUNCTION_DECL(id)
| Declaration of a flow protected function. More...
#define | MCUX_CSSL_FP_FUNCTION_DEF(id)
| Definition of a flow protected function. More...
#define | MCUX_CSSL_FP_FUNCTION_ENTRY(...)
| Flow protection handler for the function entry point. More...
#define | MCUX_CSSL_FP_FUNCTION_EXIT(...)
| Flow protection handler for the function exit point. More...
#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. More...
#define | MCUX_CSSL_FP_FUNCTION_EXIT_VOID(...)
| Flow protection handler for the exit point of functions with the return type `void`. More...
#define | MCUX_CSSL_FP_RESULT(return)
| Extract the result value from a protected `return` value. More...
#define | MCUX_CSSL_FP_PROTECTION_TOKEN(return)
| Extract the protection token value from a protected `return` value. More...
#define | MCUX_CSSL_FP_FUNCTION_CALL(...)
| Call a flow protected function. More...
#define | MCUX_CSSL_FP_FUNCTION_CALL_VOID(...)
| Call a flow protected void function. More...
#define | MCUX_CSSL_FP_FUNCTION_CALL_PROTECTED(...)
| Call a flow protected function from unprotected code. More...
#define | MCUX_CSSL_FP_FUNCTION_CALL_VOID_PROTECTED(...)
| Call a flow protected void function from unprotected code. More...
#define | MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(...)
| Call a flow protected function and check the protection token. More...
#define | MCUX_CSSL_FP_FUNCTION_CALL_END(...)
| End a function call section started by MCUX_CSSL_FP_FUNCTION_CALL_BEGIN. More...
#define | MCUX_CSSL_FP_FUNCTION_CALLED(...)
| Expectation of a called function. More...

## Detailed Description

Support for flow protected functions.

Declaration
  MCUX_CSSL_FP_FUNCTION_DECL

Event
  MCUX_CSSL_FP_FUNCTION_CALL

Expectation
  MCUX_CSSL_FP_FUNCTION_CALLED

## Macro Definition Documentation

## ◆ MCUX_CSSL_FP_PROTECTED_TYPE

#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:

MCUX_CSSL_FP_FUNCTION_DECL(someFunction)
MCUX_CSSL_FP_PROTECTED_TYPE(uint32_t) someFunction(void);

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.

See also
  MCUX_CSSL_FP_FUNCTION_DEF

Parameters

  resultType | The type to be converted into a protected type.

## ◆ MCUX_CSSL_FP_COUNTER_STMT

#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.

Parameters

  statement | The statement to be conditionally included.

## ◆ MCUX_CSSL_FP_FUNCTION_DECL

#define MCUX_CSSL_FP_FUNCTION_DECL | ( |  | id | ) |

Declaration of a flow protected function.

This declaration must be placed just in front of the actual function declaration. For example:

MCUX_CSSL_FP_FUNCTION_DECL(someFunction) // Note: no semicolon here
uint32_t someFunction(void);

Event
  MCUX_CSSL_FP_FUNCTION_CALL

Expectation
  MCUX_CSSL_FP_FUNCTION_CALLED

See also
  MCUX_CSSL_FP_FUNCTION_DEF
  MCUX_CSSL_FP_FUNCTION_ENTRY
  MCUX_CSSL_FP_FUNCTION_EXIT
  MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK

Parameters

  id | Identifier for the function that is flow protected.

## ◆ MCUX_CSSL_FP_FUNCTION_DEF

#define MCUX_CSSL_FP_FUNCTION_DEF | ( |  | id | ) |

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:

// someHeader.h
MCUX_CSSL_FP_FUNCTION_DECL(someFunction) // Note: no semicolon here
uint32_t someFunction(void);
// someFile.c
MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
uint32_t someFunction(void)
{
// some function body
}

See also
  MCUX_CSSL_FP_FUNCTION_DECL
  MCUX_CSSL_FP_FUNCTION_ENTRY
  MCUX_CSSL_FP_FUNCTION_EXIT
  MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK

Parameters

  id | Identifier for the function that is flow protected.

## ◆ MCUX_CSSL_FP_FUNCTION_ENTRY

#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:

MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
uint32_t someFunction(void)
{
MCUX_CSSL_FP_FUNCTION_ENTRY(someFunction);
// remainder of the function body
}

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:

MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
uint32_t someFunction(uint32_t count)
{
MCUX_CSSL_FP_LOOP_DECL(someLoop);
MCUX_CSSL_FP_LOOP_DECL(otherLoop);
MCUX_CSSL_FP_FUNCTION_ENTRY(someFunction,
MCUX_CSSL_FP_LOOP_ITERATIONS(someLoop, count),
MCUX_CSSL_FP_LOOP_ITERATIONS(otherLoop, 2u * count)
);
// Remainder of the function body, where someLoop makes count iterations,
// and otherLoop 2*count iterations.
}

See also
  MCUX_CSSL_FP_FUNCTION_DECL
  MCUX_CSSL_FP_FUNCTION_DEF
  MCUX_CSSL_FP_FUNCTION_EXIT
  MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK

Parameters

  ... | The following parameters need to be passed (comma separated):
  - id: Identifier of the function that has just been entered.
  - expect: Zero or more (comma separated) declarations of expected code flow behavior.

## ◆ MCUX_CSSL_FP_FUNCTION_EXIT

#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:

uint32_t someFunction(void)
{
// some function body
return 0;
}

The protected version would become:

MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
uint32_t someFunction(void)
{
MCUX_CSSL_FP_FUNCTION_ENTRY(someFunction);
// remainder of the function body
MCUX_CSSL_FP_FUNCTION_EXIT(someFunction, 0);
}

See also
  MCUX_CSSL_FP_FUNCTION_DECL
  MCUX_CSSL_FP_FUNCTION_DEF
  MCUX_CSSL_FP_FUNCTION_ENTRY
  MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK

Parameters

  ... | The following parameters need to be passed (comma separated):
  - id: Identifier of the function from which we will exit.
  - result: Result that should be encoded in the return value.
  - expect: Zero or more (comma separated) declarations of expected code flow behavior.

Returns
  A value in which both `result` and a flow protection token are encoded.

## ◆ MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK

#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:

MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
uint32_t someFunction(void)
{
MCUX_CSSL_FP_FUNCTION_ENTRY(someFunction);
// remainder of the function body
MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK(someFunction, 0, 0xFAu);
}

See also
  MCUX_CSSL_FP_FUNCTION_DECL
  MCUX_CSSL_FP_FUNCTION_DEF
  MCUX_CSSL_FP_FUNCTION_ENTRY
  MCUX_CSSL_FP_FUNCTION_EXIT

Parameters

  ... | The following parameters need to be passed (comma separated):
  - id: Identifier of the function from which we will exit.
  - pass: Result that should be encoded in the return value if the flow protection check passed.
  - fail: Result that should be encoded in the return value if the flow protection check failed.
  - expect: Zero or more (comma separated) declarations of expected code flow behavior.

Returns
  A value in which both the result (either `pass` or `fail`) and a flow protection token are encoded.

## ◆ MCUX_CSSL_FP_FUNCTION_EXIT_VOID

#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:

void someFunction(void)
{
// some function body
return 0;
}

The protected version would become:

MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
void someFunction(void)
{
MCUX_CSSL_FP_FUNCTION_ENTRY(someFunction);
// remainder of the function body
MCUX_CSSL_FP_FUNCTION_EXIT_VOID(someFunction);
}

See also
  MCUX_CSSL_FP_FUNCTION_DECL
  MCUX_CSSL_FP_FUNCTION_DEF
  MCUX_CSSL_FP_FUNCTION_ENTRY

Parameters

  ... | The following parameters need to be passed (comma separated):
  - id: Identifier of the function from which we will exit.
  - expect: Zero or more (comma separated) declarations of expected code flow behavior.

Returns
  A protected return value of type void.

## ◆ MCUX_CSSL_FP_RESULT

#define MCUX_CSSL_FP_RESULT | ( |  | return | ) |

Extract the result value from a protected `return` value.

Parameters

  return | The protected return value which contains the result.

## ◆ MCUX_CSSL_FP_PROTECTION_TOKEN

#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

Parameters

  return | The protected return value which contains the protection token.

## ◆ MCUX_CSSL_FP_FUNCTION_CALL

#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:

MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
uint32_t someFunction(void)
{
MCUX_CSSL_FP_FUNCTION_ENTRY(someFunction);
// ...
MCUX_CSSL_FP_FUNCTION_CALL(result, otherFunction());
// ...
MCUX_CSSL_FP_FUNCTION_EXIT(someFunction, 0,
MCUX_CSSL_FP_FUNCTION_CALLED(otherFunction)
);
}

For functions returning void, the macro MCUX_CSSL_FP_FUNCTION_CALL_VOID exists.

Declaration
  MCUX_CSSL_FP_FUNCTION_DECL

Expectation
  MCUX_CSSL_FP_FUNCTION_CALLED

Parameters

  ... | The following parameters need to be passed (comma separated):
  - result: Fresh variable name to store the result of `call`.
  - call: The (protected) function call that must be performed.

## ◆ MCUX_CSSL_FP_FUNCTION_CALL_VOID

#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:

MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
uint32_t someFunction(void)
{
MCUX_CSSL_FP_FUNCTION_ENTRY(someFunction);
// ...
MCUX_CSSL_FP_FUNCTION_CALL_VOID(otherFunction());
// ...
MCUX_CSSL_FP_FUNCTION_EXIT(someFunction, 0,
MCUX_CSSL_FP_FUNCTION_CALLED(otherFunction)
);
}

Declaration
  MCUX_CSSL_FP_FUNCTION_DECL

Expectation
  MCUX_CSSL_FP_FUNCTION_CALLED

Parameters

  ... | The following parameters need to be passed (comma separated):
  - call: The (protected) void function call that must be performed.

## ◆ MCUX_CSSL_FP_FUNCTION_CALL_PROTECTED

#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:

uint32_t someUnprotectedFunction(void)
{
// ...
MCUX_CSSL_FP_FUNCTION_CALL_PROTECTED(
result,
token,
otherFunction());
// Check the protection token
if(MCUX_CSSL_FP_FUNCTION_CALLED(otherFunction) != token)
{
return FAULT;
}
// ... The following code may use 'result' as a variable ...
}

Parameters

  ... | The following parameters need to be passed (comma separated):
  - result: Fresh variable name to store the result of `call`.
  - token: Fresh variable name to store the protection token of `call`.
  - call: The (protected) function call that must be performed.

## ◆ MCUX_CSSL_FP_FUNCTION_CALL_VOID_PROTECTED

#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:

uint32_t someUnprotectedFunction(void)
{
// ...
MCUX_CSSL_FP_FUNCTION_CALL_PROTECTED(
token,
protectedVoidFunction());
// Check the protection token
if(MCUX_CSSL_FP_FUNCTION_CALLED(otherFunction) != token)
{
return FAULT;
}
// ...
}

Parameters

  ... | The following parameters need to be passed (comma separated):
  - token: Fresh variable name to store the protection token of `call`.
  - call: The (protected) function call that must be performed.

## ◆ MCUX_CSSL_FP_FUNCTION_CALL_BEGIN

#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:

uint32_t someUnprotectedFunction(void)
{
// ...
MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(
result,
token,
otherFunction());
// Check the protection token
if(MCUX_CSSL_FP_FUNCTION_CALLED(otherFunction) != token)
{
return FAULT;
}
// ... The following code may use 'result' as a variable ...
MCUX_CSSL_FP_FUNCTION_CALL_END();
// ... result is invalid here ...
}

Parameters

  ... | The following parameters need to be passed (comma separated):
  - result: Fresh variable name to store the result of `call`.
  - token: Fresh variable name to store the protection token of `call`.
  - call: The (protected) function call that must be performed.

Examples
  cipher_aes128_cbc_encrypt.c, cipher_aes128_ecb_encrypt.c, common_get_info.c, ecc_keygen_sign_verify.c, hash_sha224_one_block.c, hash_sha256_one_block.c, hash_sha256_sha_direct_one_block.c, hash_sha384_one_block.c, hash_sha384_sha_direct_one_block.c, hash_sha512_one_block.c, mcuxClEcc_Mont_example.c, mcuxClKey_example.c, mcuxClMac_cmac_oneshot_example.c, mcuxClRsa_sign_NoEncode_example.c, mcuxClRsa_sign_pss_sha2_256_example.c, mcuxClRsa_verify_NoVerify_example.c, mcuxClRsa_verify_pssverify_sha2_256_example.c, rng_prng_get_random.c, and tls_master_key_session_keys.c.

## ◆ MCUX_CSSL_FP_FUNCTION_CALL_END

#define MCUX_CSSL_FP_FUNCTION_CALL_END | ( |  | ... | ) |

End a function call section started by MCUX_CSSL_FP_FUNCTION_CALL_BEGIN.

Example:

uint32_t someUnprotectedFunction(void)
{
// ...
MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(
result,
token,
otherFunction());
// Check the protection token
if(MCUX_CSSL_FP_FUNCTION_CALLED(otherFunction) != token)
{
return FAULT;
}
// ... The following code may use 'result' as a variable ...
MCUX_CSSL_FP_FUNCTION_CALL_END();
// ... result is invalid here ...
}

Parameters

  ... | The following parameters need to be passed (comma separated):
  - result: Fresh variable name to store the result of `call`.
  - token: Fresh variable name to store the protection token of `call`.
  - call: The (protected) function call that must be performed.

Examples
  cipher_aes128_cbc_encrypt.c, cipher_aes128_ecb_encrypt.c, common_get_info.c, ecc_keygen_sign_verify.c, hash_sha224_one_block.c, hash_sha256_one_block.c, hash_sha256_sha_direct_one_block.c, hash_sha384_one_block.c, hash_sha384_sha_direct_one_block.c, hash_sha512_one_block.c, mcuxClEcc_Mont_example.c, mcuxClKey_example.c, mcuxClMac_cmac_oneshot_example.c, mcuxClRsa_sign_NoEncode_example.c, mcuxClRsa_sign_pss_sha2_256_example.c, mcuxClRsa_verify_NoVerify_example.c, mcuxClRsa_verify_pssverify_sha2_256_example.c, rng_prng_get_random.c, and tls_master_key_session_keys.c.

## ◆ MCUX_CSSL_FP_FUNCTION_CALLED

#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:

MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
uint32_t someFunction(void)
{
MCUX_CSSL_FP_FUNCTION_ENTRY(someFunction,
MCUX_CSSL_FP_FUNCTION_CALLED(otherFunction)
);
// ...
MCUX_CSSL_FP_FUNCTION_CALL(result, otherFunction());
// ...
MCUX_CSSL_FP_FUNCTION_EXIT(someFunction, 0);
}

Or that a function call has happened (if placed after the actual call), for example:

MCUX_CSSL_FP_FUNCTION_DEF(someFunction) // Note: no semicolon here
uint32_t someFunction(void)
{
MCUX_CSSL_FP_FUNCTION_ENTRY(someFunction);
// ...
MCUX_CSSL_FP_FUNCTION_CALL(result, otherFunction());
// ...
MCUX_CSSL_FP_FUNCTION_EXIT(someFunction, 0,
MCUX_CSSL_FP_FUNCTION_CALLED(otherFunction)
);
}

Declaration
  MCUX_CSSL_FP_FUNCTION_DECL

Event
  MCUX_CSSL_FP_FUNCTION_CALL

See also
  MCUX_CSSL_FP_FUNCTION_ENTRY
  MCUX_CSSL_FP_FUNCTION_EXIT
  MCUX_CSSL_FP_FUNCTION_EXIT_WITH_CHECK
  MCUX_CSSL_FP_EXPECT

Parameters

  ... | The following parameters need to be passed (comma separated): -id: Identifier of the function that is expected to be called.

Examples
  cipher_aes128_cbc_encrypt.c, cipher_aes128_ecb_encrypt.c, common_get_info.c, ecc_keygen_sign_verify.c, hash_sha224_one_block.c, hash_sha256_one_block.c, hash_sha256_sha_direct_one_block.c, hash_sha384_one_block.c, hash_sha384_sha_direct_one_block.c, hash_sha512_one_block.c, mcuxClEcc_Mont_example.c, mcuxClKey_example.c, mcuxClMac_cmac_oneshot_example.c, mcuxClRsa_sign_NoEncode_example.c, mcuxClRsa_sign_pss_sha2_256_example.c, mcuxClRsa_verify_NoVerify_example.c, mcuxClRsa_verify_pssverify_sha2_256_example.c, rng_prng_get_random.c, and tls_master_key_session_keys.c.