1 /*--------------------------------------------------------------------------*/ 2 /* Copyright 2020 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 mcuxCsslSecureCounter.h 16 * @brief Provides the API for the CSSL secure counter mechanism. 17 */ 18 19 #ifndef MCUX_CSSL_SECURE_COUNTER_H_ 20 #define MCUX_CSSL_SECURE_COUNTER_H_ 21 22 /* Include the actual implementation of the secure counter mechanism. */ 23 #include <internal/mcuxCsslSecureCounter_Impl.h> 24 25 /** 26 * @addtogroup mcuxCsslAPI MCUX CSSL -- API 27 * 28 * @defgroup mcuxCsslSecureCounter Secure Counter API 29 * @brief Secure counter mechanism. 30 * @ingroup mcuxCsslAPI 31 */ 32 33 34 /** 35 * @defgroup scCore Secure counter core functionality 36 * @brief Secure counter handling core functionality. 37 * @ingroup mcuxCsslSecureCounter 38 * 39 * @todo Extend this description of the core functionality. 40 */ 41 42 /****************************************************************************/ 43 /* Constants */ 44 /****************************************************************************/ 45 46 /** 47 * @def MCUX_CSSL_SC_CHECK_PASSED 48 * @brief Positive comparison result value. 49 * @api 50 * @ingroup scCore 51 */ 52 #define MCUX_CSSL_SC_CHECK_PASSED \ 53 MCUX_CSSL_SC_CHECK_PASSED_IMPL 54 55 /** 56 * @def MCUX_CSSL_SC_CHECK_FAILED 57 * @brief Negative comparison result value. 58 * @api 59 * @ingroup scCore 60 */ 61 #define MCUX_CSSL_SC_CHECK_FAILED \ 62 MCUX_CSSL_SC_CHECK_FAILED_IMPL 63 64 /** 65 * @def MCUX_CSSL_SC_VALUE_TYPE 66 * @brief Data type used for the secure counter values. 67 * @api 68 * @ingroup scCore 69 */ 70 #define MCUX_CSSL_SC_VALUE_TYPE \ 71 MCUX_CSSL_SC_VALUE_TYPE_IMPL 72 73 /****************************************************************************/ 74 /* Initialization */ 75 /****************************************************************************/ 76 77 /** 78 * @def MCUX_CSSL_SC_ALLOC 79 * @brief Allocation operation for the secure counter. 80 * @api 81 * @ingroup scCore 82 */ 83 #define MCUX_CSSL_SC_ALLOC() \ 84 MCUX_CSSL_SC_ALLOC_IMPL() 85 86 /** 87 * @def MCUX_CSSL_SC_INIT 88 * @brief Initialization operation for the secure counter. 89 * @api 90 * @ingroup scCore 91 * 92 * @param value Value with which the secure counter must be initialized. 93 */ 94 #define MCUX_CSSL_SC_INIT(value) \ 95 MCUX_CSSL_SC_INIT_IMPL(value) 96 97 /****************************************************************************/ 98 /* Check */ 99 /****************************************************************************/ 100 101 /** 102 * @def MCUX_CSSL_SC_CHECK 103 * @brief Comparison operation for the secure counter. 104 * @api 105 * @ingroup scCore 106 * 107 * @param reference Reference value to compare the secure counter value against. 108 * @return Either #MCUX_CSSL_SC_CHECK_PASSED, if the value matches, or 109 * #MCUX_CSSL_SC_CHECK_FAILED if the value is different. 110 */ 111 #define MCUX_CSSL_SC_CHECK(reference) \ 112 MCUX_CSSL_SC_CHECK_IMPL(reference) 113 114 /****************************************************************************/ 115 /* Counter increment */ 116 /****************************************************************************/ 117 /** 118 * @defgroup scInc Secure counter increment 119 * @brief Support for incrementing the secure counter. 120 * @ingroup mcuxCsslSecureCounter 121 */ 122 123 /** 124 * @def MCUX_CSSL_SC_ADD 125 * @brief Increment the secure counter with @p value. 126 * @api 127 * @ingroup scInc 128 * 129 * @see MCUX_CSSL_SC_ADD_0x1 130 * @see MCUX_CSSL_SC_ADD_0x10 131 * @see MCUX_CSSL_SC_ADD_0x100 132 * @see MCUX_CSSL_SC_SUB 133 * 134 * @param value Value with which the secure counter must be incremented. 135 */ 136 #define MCUX_CSSL_SC_ADD(value) \ 137 MCUX_CSSL_SC_ADD_IMPL(value) 138 139 /** 140 * @def MCUX_CSSL_SC_ADD_0x1 141 * @brief Increment the secure counter with 0x1. 142 * @api 143 * @ingroup scInc 144 * 145 * @see MCUX_CSSL_SC_ADD 146 * @see MCUX_CSSL_SC_ADD_0x10 147 * @see MCUX_CSSL_SC_ADD_0x100 148 * @see MCUX_CSSL_SC_SUB_0x1 149 */ 150 #define MCUX_CSSL_SC_ADD_0x1() \ 151 MCUX_CSSL_SC_ADD_0x1_IMPL() 152 153 /** 154 * @def MCUX_CSSL_SC_ADD_0x10 155 * @brief Increment the secure counter with 0x10. 156 * @api 157 * @ingroup scInc 158 * 159 * @see MCUX_CSSL_SC_ADD 160 * @see MCUX_CSSL_SC_ADD_0x1 161 * @see MCUX_CSSL_SC_ADD_0x100 162 * @see MCUX_CSSL_SC_SUB_0x10 163 */ 164 #define MCUX_CSSL_SC_ADD_0x10() \ 165 MCUX_CSSL_SC_ADD_0x10_IMPL() 166 167 /** 168 * @def MCUX_CSSL_SC_ADD_0x100 169 * @brief Increment the secure counter with 0x100. 170 * @api 171 * @ingroup scInc 172 * 173 * @see MCUX_CSSL_SC_ADD 174 * @see MCUX_CSSL_SC_ADD_0x1 175 * @see MCUX_CSSL_SC_ADD_0x10 176 * @see MCUX_CSSL_SC_SUB_0x100 177 */ 178 #define MCUX_CSSL_SC_ADD_0x100() \ 179 MCUX_CSSL_SC_ADD_0x100_IMPL() 180 181 /****************************************************************************/ 182 /* Counter decrement */ 183 /****************************************************************************/ 184 /** 185 * @defgroup scDec Secure counter decrement 186 * @brief Support for decrementing the secure counter. 187 * @ingroup mcuxCsslSecureCounter 188 */ 189 190 /** 191 * @def MCUX_CSSL_SC_SUB 192 * @brief Decrement the secure counter with @p value. 193 * @api 194 * @ingroup scDec 195 * 196 * @see MCUX_CSSL_SC_SUB_0x1 197 * @see MCUX_CSSL_SC_SUB_0x10 198 * @see MCUX_CSSL_SC_SUB_0x100 199 * @see MCUX_CSSL_SC_ADD 200 * 201 * @param value Value with which the secure counter must be decremented. 202 */ 203 #define MCUX_CSSL_SC_SUB(value) \ 204 MCUX_CSSL_SC_SUB_IMPL(value) 205 206 /** 207 * @def MCUX_CSSL_SC_SUB_0x1 208 * @brief Decrement the secure counter with 0x1. 209 * @api 210 * @ingroup scDec 211 * 212 * @see MCUX_CSSL_SC_SUB 213 * @see MCUX_CSSL_SC_SUB_0x10 214 * @see MCUX_CSSL_SC_SUB_0x100 215 * @see MCUX_CSSL_SC_ADD_0x1 216 */ 217 #define MCUX_CSSL_SC_SUB_0x1() \ 218 MCUX_CSSL_SC_SUB_0x1_IMPL() 219 220 /** 221 * @def MCUX_CSSL_SC_SUB_0x10 222 * @brief Decrement the secure counter with 0x10. 223 * @api 224 * @ingroup scDec 225 * 226 * @see MCUX_CSSL_SC_SUB 227 * @see MCUX_CSSL_SC_SUB_0x1 228 * @see MCUX_CSSL_SC_SUB_0x100 229 * @see MCUX_CSSL_SC_ADD_0x10 230 */ 231 #define MCUX_CSSL_SC_SUB_0x10() \ 232 MCUX_CSSL_SC_SUB_0x10_IMPL() 233 234 /** 235 * @def MCUX_CSSL_SC_SUB_0x100 236 * @brief Decrement the secure counter with 0x100. 237 * @api 238 * @ingroup scDec 239 * 240 * @see MCUX_CSSL_SC_SUB 241 * @see MCUX_CSSL_SC_SUB_0x1 242 * @see MCUX_CSSL_SC_SUB_0x10 243 * @see MCUX_CSSL_SC_ADD_0x100 244 */ 245 #define MCUX_CSSL_SC_SUB_0x100() \ 246 MCUX_CSSL_SC_SUB_0x100_IMPL() 247 248 /****************************************************************************/ 249 /* Direct access (optional) */ 250 /****************************************************************************/ 251 /** 252 * @defgroup scDirect Secure counter direct access 253 * @brief Support for directly accessing the secure counter. 254 * @ingroup mcuxCsslSecureCounter 255 * 256 * @warning Access to the secure counter is generally restricted, and generic 257 * access might not be allowed. 258 */ 259 260 /** 261 * @def MCUX_CSSL_SC_VALUE 262 * @brief Access operation for the current secure counter value. 263 * @api 264 * @ingroup scDirect 265 * 266 * @warning Access to the secure counter is generally restricted, and generic 267 * access might not be allowed. For portable code it is best to only rely on 268 * the check operation to verify the secure counter value. 269 * 270 * @return The current value of the secure counter. 271 */ 272 #define MCUX_CSSL_SC_VALUE() \ 273 MCUX_CSSL_SC_VALUE_IMPL() 274 275 /** 276 * @def MCUX_CSSL_SC_ASSIGN 277 * @brief Assignment operation for the secure counter. 278 * @api 279 * @ingroup scDirect 280 * 281 * @warning Access to the secure counter is generally restricted, and generic 282 * assignment might not be allowed. For portable code it is best to only rely 283 * on the initialization, increment and decrement operations to change the 284 * secure counter value. 285 * 286 * @param value Value that needs to be assigned to the secure counter. 287 */ 288 #define MCUX_CSSL_SC_ASSIGN(value) \ 289 MCUX_CSSL_SC_ASSIGN_IMPL(value) 290 291 #endif /* MCUX_CSSL_SECURE_COUNTER_H_ */ 292
