1 /* 2 * Copyright (c) 2022-2024, Arm Limited. All rights reserved. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * \file kmu_drv.h 19 * \brief Driver for Arm KMU. 20 */ 21 22 #ifndef __KMU_DRV_H__ 23 #define __KMU_DRV_H__ 24 25 #include <stdint.h> 26 #include <stdbool.h> 27 #include <stddef.h> 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /* Must be at least 16 */ 34 #define KMU_PRBG_SEED_LEN (32) 35 36 #define KMU_GET_NKS(kmu_base) ( \ 37 1 << (uint8_t)(((kmu_base)->kmubc & KMU_KMUBC_NKS_MASK) >> KMU_KMUBC_NKS_OFF)) 38 39 #define KMU_GET_NHWKSLTS(kmu_base) ( \ 40 (uint8_t)(((kmu_base)->kmubc & KMU_KMUBC_NHWKSLTS_MASK) >> \ 41 KMU_KMUBC_NHWKSLTS_OFF)) 42 43 #define KMU_KMUBC_NKS_OFF 16u 44 /*!< KMU Build Configuration Register Number of Key Slots bit field offset 45 */ 46 #define KMU_KMUBC_NKS_MASK (0x7u<<KMU_KMUBC_NKS_OFF) 47 /*!< KMU Build Configuration Register Number of Key Slots bit field mask */ 48 #define KMU_KMUBC_NHWKSLTS_OFF 19u 49 /*!< KMU Build Configuration Register Number of Hardware Key Slots bit 50 * field offset */ 51 #define KMU_KMUBC_NHWKSLTS_MASK (0xFu<<KMU_KMUBC_NHWKSLTS_OFF) 52 /*!< KMU Build Configuration Register Number of Hardware Key Slots bit 53 * field mask */ 54 55 #define KMU_KMISR_KEC_MASK (0x1u << 0u) 56 /*!< KMU Interrupt Status Register Key Export Complete bit field mask */ 57 #define KMU_KMISR_AWBE_MASK (0x1u << 1u) 58 /*!< KMU Interrupt Status Register Activation While Busy Error bit field 59 * mask */ 60 #define KMU_KMISR_IPE_MASK (0x1u << 2u) 61 /*!< KMU Interrupt Status Register Internal Parity Error bit field mask */ 62 #define KMU_KMISR_INPPE_MASK (0x1u << 3u) 63 /*!< KMU Interrupt Status Register Input Parity Error bit field mask */ 64 #define KMU_KMISR_WDADDKPA_MASK (0x1u << 4u) 65 /*!< KMU Interrupt Status Register Wrong Destination Address Detected 66 * bit field mask */ 67 #define KMU_KMISR_WTE_MASK (0x1u << 5u) 68 /*!< KMU Interrupt Status Register Write Transaction Error bit field mask 69 */ 70 #define KMU_KMISR_AEWNR_MASK (0x1u << 6u) 71 /*!< KMU Interrupt Status Register Attempted to Export While Not Ready bit 72 * field mask */ 73 #define KMU_KMISR_KSNL_MASK (0x1u << 7u) 74 /*!< KMU Interrupt Status Register Key Slot Not Locked bit field mask */ 75 #define KMU_KMISR_KSKRSM_MASK (0x1u << 8u) 76 /*!< KMU Interrupt Status Register Key Slot Register Size Mismatch bit 77 * field mask */ 78 #define KMU_KMISR_KSDPANS_MASK (0x1u << 9u) 79 /*!< KMU Interrupt Status Register Key Slot Destination Port Register Not 80 * Set bit field mask */ 81 #define KMU_KMISR_AIKSWE_MASK (0x1u << 10u) 82 /*!< KMU Interrupt Status Register Attempted to Invalidate Key Slot While 83 * Exporting bit field mask */ 84 #define KMU_KMISR_MWKSW_MASK (0x1u << 11u) 85 /*!< KMU Interrupt Status Register Multiple Writes to Key Slot Word bit 86 * field mask */ 87 #define KMU_KMISR_AKSWPI_MASK (0x1u << 12u) 88 /*!< KMU Interrupt Status Register Attempt to Write to Key Slot Word 89 * Register when it is Permanently Invalidated bit field mask */ 90 #define KMU_KMISR_AWBHKSKR_MASK (0x1u << 13u) 91 /*!< KMU Interrupt Status Register Attempt to Write from the Private APB HW 92 * Keys Port to Beyond the Hardware Key Slot Registers bit field mask */ 93 #define KMU_KMISR_WDALSBDKPA_MASK (0x1u << 14u) 94 /*!< KMU Interrupt Status Register Wrong Destination Address LS Bits 95 * Detected bit field mask */ 96 97 #define KMU_KMUKSC_DPWD_OFF 0u 98 /*!< KMU Key Slot Configuration Register Destination Port Write Delay bit 99 * field offset */ 100 #define KMU_KMUKSC_DPWD_MASK (0xFFu<<KMU_KMUKSC_DPWD_OFF) 101 /*!< KMU Key Slot Configuration Register Destination Port Write Delay bit 102 * field mask */ 103 #define KMU_KMUKSC_DPAI_OFF 8u 104 /*!< KMU Key Slot Configuration Register Destination Port Address Incrememt 105 * bit field offset */ 106 #define KMU_KMUKSC_DPAI_MASK (0xFFu<<KMU_KMUKSC_DPAI_OFF) 107 /*!< KMU Key Slot Configuration Register Destination Port Address Incrememt 108 * bit field mask */ 109 #define KMU_KMUKSC_DPDW_OFF 16u 110 /*!< KMU Key Slot Configuration Register Destination Port Data Width bit 111 * field offset */ 112 #define KMU_KMUKSC_DPDW_MASK (0x3u<<KMU_KMUKSC_DPDW_OFF) 113 /*!< KMU Key Slot Configuration Register Destination Port Data Width bit 114 * field mask */ 115 #define KMU_KMUKSC_NDPW_OFF 18u 116 /*!< KMU Key Slot Configuration Register Num Destination Port Writes bit 117 * field offset */ 118 #define KMU_KMUKSC_NDPW_MASK (0x3u<<KMU_KMUKSC_NDPW_OFF) 119 /*!< KMU Key Slot Configuration Register Num Destination Port Writes bit 120 * field mask */ 121 #define KMU_KMUKSC_NMNKW_OFF 20u 122 /*!< KMU Key Slot Configuration Register New Mask for Next Kew Writes bit 123 * field offset */ 124 #define KMU_KMUKSC_NMNKW_MASK (0x1u<<KMU_KMUKSC_NMNKW_OFF) 125 /*!< KMU Key Slot Configuration Register New Mask for Next Kew Writes bit 126 * field mask */ 127 #define KMU_KMUKSC_WMD_OFF 21u 128 /*!< KMU Key Slot Configuration Register Write Mask Disable bit field 129 * offset */ 130 #define KMU_KMUKSC_WMD_MASK (0x1u<<KMU_KMUKSC_WMD_OFF) 131 /*!< KMU Key Slot Configuration Register Write Mask Disable bit field 132 * mask */ 133 #define KMU_KMUKSC_WMD_OFF 21u 134 /*!< KMU Key Slot Configuration Register Write Mask Disable bit field 135 * offset */ 136 #define KMU_KMUKSC_WMD_MASK (0x1u<<KMU_KMUKSC_WMD_OFF) 137 /*!< KMU Key Slot Configuration Register Write Mask Disable bit field 138 * mask */ 139 #define KMU_KMUKSC_LKS_OFF 22u 140 /*!< KMU Key Slot Configuration Register Lock Key Slot bit field offset */ 141 #define KMU_KMUKSC_LKS_MASK (0x1u<<KMU_KMUKSC_LKS_OFF) 142 /*!< KMU Key Slot Configuration Register Lock Key Slot bit field mask */ 143 #define KMU_KMUKSC_LKSKR_OFF 23u 144 /*!< KMU Key Slot Configuration Register Lock Key Slot Key Registers bit 145 * field offset */ 146 #define KMU_KMUKSC_LKSKR_MASK (0x1u<<KMU_KMUKSC_LKSKR_OFF) 147 /*!< KMU Key Slot Configuration Register Lock Key Slot Key Registers bit 148 * field mask */ 149 #define KMU_KMUKSC_VKS_OFF 24u 150 /*!< KMU Key Slot Configuration Register Verify Key Slot bit field offset 151 */ 152 #define KMU_KMUKSC_VKS_MASK (0x1u<<KMU_KMUKSC_VKS_OFF) 153 /*!< KMU Key Slot Configuration Register Verify Key Slot bit field mask */ 154 #define KMU_KMUKSC_KSR_OFF 25u 155 /*!< KMU Key Slot Configuration Register Key Slot Ready bit field offset */ 156 #define KMU_KMUKSC_KSR_MASK (0x1u<<KMU_KMUKSC_KSR_OFF) 157 /*!< KMU Key Slot Configuration Register Key Slot Ready bit field mask */ 158 #define KMU_KMUKSC_IKS_OFF 26u 159 /*!< KMU Key Slot Configuration Register Invalidate Key Slot bit field 160 * offset */ 161 #define KMU_KMUKSC_IKS_MASK (0x1u<<KMU_KMUKSC_IKS_OFF) 162 /*!< KMU Key Slot Configuration Register Invalidate Key Slot bit field 163 * mask */ 164 #define KMU_KMUKSC_KSIP_OFF 27u 165 /*!< KMU Key Slot Configuration Register Key Slot Invalidated Permanently 166 * bit field offset */ 167 #define KMU_KMUKSC_KSIP_MASK (0x1u<<KMU_KMUKSC_KSIP_OFF) 168 /*!< KMU Key Slot Configuration Register Key Slot Invalidated Permanently 169 * bit field mask */ 170 #define KMU_KMUKSC_EK_OFF 28u 171 /*!< KMU Key Slot Configuration Register Export Key bit field offset */ 172 #define KMU_KMUKSC_EK_MASK (0x1u<<KMU_KMUKSC_EK_OFF) 173 /*!< KMU Key Slot Configuration Register Export Key bit field mask */ 174 #define KMU_KMUKSC_L_KMUPRBGSI_OFF 31u 175 /*!< KMU Key Slot Configuration Register Lock KMUPRBGSI bit field offset */ 176 #define KMU_KMUKSC_L_KMUPRBGSI_MASK (0x1u<<KMU_KMUKSC_L_KMUPRBGSI_OFF) 177 /*!< KMU Key Slot Configuration Register Lock KMUPRBGSI bit field mask */ 178 179 /** 180 * \brief ARM KMU error enumeration types 181 */ 182 enum kmu_error_t { 183 KMU_ERROR_NONE = (0x0u), 184 KMU_ERROR_INVALID_ALIGNMENT, 185 KMU_ERROR_INVALID_LENGTH, 186 KMU_ERROR_INVALID_SLOT, 187 KMU_ERROR_INVALID_EXPORT_ADDR, 188 KMU_ERROR_SLOT_LOCKED, 189 KMU_ERROR_SLOT_NOT_LOCKED, 190 KMU_ERROR_SLOT_INVALIDATED, 191 KMU_ERROR_SLOT_ALREADY_WRITTEN, 192 KMU_ERROR_NOT_READY, 193 KMU_ERROR_INTERNAL_ERROR, 194 KMU_ERROR_INVALID_DELAY_LENGTH, 195 }; 196 197 enum kmu_hardware_keyslot_t { 198 KMU_HW_SLOT_KRTL = (0u), 199 KMU_HW_SLOT_HUK, 200 KMU_HW_SLOT_GUK, 201 KMU_HW_SLOT_KP_CM, 202 KMU_HW_SLOT_KCE_CM, 203 KMU_HW_SLOT_KP_DM, 204 KMU_HW_SLOT_KCE_DM, 205 KMU_USER_SLOT_MIN = (7u), 206 KMU_USER_SLOT_MAX = (31u), 207 }; 208 209 enum kmu_destination_port_data_width_t { 210 KMU_DESTINATION_PORT_WIDTH_8_BITS = (0x0u), 211 KMU_DESTINATION_PORT_WIDTH_16_BITS, 212 KMU_DESTINATION_PORT_WIDTH_32_BITS, 213 }; 214 215 enum kmu_destination_port_data_writes_t { 216 KMU_DESTINATION_PORT_WIDTH_4_WRITES = (0x0u), 217 KMU_DESTINATION_PORT_WIDTH_8_WRITES, 218 KMU_DESTINATION_PORT_WIDTH_16_WRITES, 219 KMU_DESTINATION_PORT_WIDTH_32_WRITES, 220 }; 221 222 enum kmu_delay_limit_t { 223 KMU_DELAY_LIMIT_8_CYCLES, 224 KMU_DELAY_LIMIT_16_CYCLES, 225 KMU_DELAY_LIMIT_32_CYCLES, 226 }; 227 228 /** 229 * \brief ARM KMU export policy configuration structure 230 */ 231 struct kmu_key_export_config_t { 232 uint32_t export_address; 233 uint8_t destination_port_write_delay; 234 uint8_t destination_port_address_increment; 235 enum kmu_destination_port_data_width_t destination_port_data_width_code; 236 enum kmu_destination_port_data_writes_t destination_port_data_writes_code; 237 bool new_mask_for_next_key_writes; 238 bool write_mask_disable; 239 }; 240 241 /** 242 * \brief ARM KMU device configuration structure 243 */ 244 struct kmu_dev_cfg_t { 245 const uint32_t base; /*!< KMU base address */ 246 }; 247 248 /** 249 * \brief ARM KMU device structure 250 */ 251 struct kmu_dev_t { 252 const struct kmu_dev_cfg_t *const cfg; /*!< KMU configuration */ 253 }; 254 255 enum kmu_error_t kmu_init(struct kmu_dev_t *dev, uint8_t *prbg_seed); 256 257 enum kmu_error_t kmu_get_key_export_config(struct kmu_dev_t *dev, uint32_t slot, 258 struct kmu_key_export_config_t *config); 259 enum kmu_error_t kmu_set_key_export_config(struct kmu_dev_t *dev, uint32_t slot, 260 const struct kmu_key_export_config_t *config); 261 262 enum kmu_error_t kmu_set_key_locked(struct kmu_dev_t *dev, uint32_t slot); 263 enum kmu_error_t kmu_get_key_locked(struct kmu_dev_t *dev, uint32_t slot); 264 265 enum kmu_error_t kmu_set_key_export_config_locked(struct kmu_dev_t *dev, 266 uint32_t slot); 267 enum kmu_error_t kmu_get_key_export_config_locked(struct kmu_dev_t *dev, 268 uint32_t slot); 269 270 enum kmu_error_t kmu_set_slot_invalid(struct kmu_dev_t *dev, uint32_t slot); 271 enum kmu_error_t kmu_get_slot_invalid(struct kmu_dev_t *dev, uint32_t slot); 272 273 enum kmu_error_t kmu_set_key(struct kmu_dev_t *dev, uint32_t slot, uint8_t *key, 274 size_t key_len); 275 enum kmu_error_t kmu_get_key(struct kmu_dev_t *dev, uint32_t slot, uint8_t *buf, 276 size_t buf_len); 277 278 enum kmu_error_t kmu_get_key_buffer_ptr(struct kmu_dev_t *dev, uint32_t slot, 279 volatile uint32_t **key_slot, 280 size_t *slot_size); 281 282 enum kmu_error_t kmu_reset_slot(struct kmu_dev_t *dev, uint32_t slot); 283 284 enum kmu_error_t kmu_export_key(struct kmu_dev_t *dev, uint32_t slot); 285 286 enum kmu_error_t kmu_random_delay(struct kmu_dev_t *dev, 287 enum kmu_delay_limit_t limit); 288 289 #ifdef __cplusplus 290 } 291 #endif 292 293 #endif /* __KMU_DRV_H__ */ 294
