1 /* 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * Description: KV Storage Library key access interface 15 */ 16 17 #ifndef NV_KEY_H 18 #define NV_KEY_H 19 20 #include "stdbool.h" 21 #include "errcode.h" 22 23 #ifdef __cplusplus 24 #if __cplusplus 25 extern "C" { 26 #endif /* __cplusplus */ 27 #endif /* __cplusplus */ 28 29 #define KV_KEY_MAGIC 0xA9 30 #define KV_KEY_VALID 0xFF 31 #define KV_KEY_INVALID 0 32 #define KV_KEY_NO_MAGIC 0xFF 33 34 #define KV_KEY_TYPE_NORMAL 0xFF 35 #define KV_KEY_TYPE_PERMANENT 0 36 37 #define KV_KEY_FORCE_UPDATE 0xf0 38 39 #define KV_CRYPTO_HASH_SIZE 32 40 #define KV_CRYPTO_CRC_SIZE 4 41 #define KV_CRYPTO_CRC32_SIZE 32 42 #define AES_BLOCK_SIZE 16 43 #define NV_AES_GCM_TAG_LENGTH 16 44 #define MIN_AES_DECRYPT_LEN (2 * AES_BLOCK_SIZE) 45 #define AES_KDFKEY_SDRK_TYPE 0x52 46 #define CRC_SWAP_SIZE8 8 47 #define CRC_SWAP_SIZE24 24 48 #define INVAILD_CRYPTO_HANDLE 0xFFFFFFFF 49 50 typedef enum { 51 KV_KEY_FILTER_STATE_VALID = 0x01, 52 KV_KEY_FILTER_STATE_INVALID = 0x02, 53 KV_KEY_FILTER_STATE_ANY = 0x03 54 } kv_key_filter_state_t; 55 56 typedef enum { 57 KV_KEY_FILTER_TYPE_NORMAL = 0x01, 58 KV_KEY_FILTER_TYPE_PERMANENT = 0x02, 59 KV_KEY_FILTER_TYPE_ANY = 0x03 60 } kv_key_filter_type_t; 61 62 /** 63 * KV key attribute flags 64 */ 65 typedef enum { 66 KV_ATTRIBUTE_PERMANENT = 0x1, /* Key is permanent and can't be deleted or modified */ 67 KV_ATTRIBUTE_ENCRYPTED = 0x2, /* Key is encrypted in flash */ 68 KV_ATTRIBUTE_NON_UPGRADE = 0x4 /* key cannot be modified during the upgrade. */ 69 } kv_attributes_t; 70 71 typedef enum { 72 KV_KEY_NOT_VALIDATE, 73 KV_KEY_VALIDATE_CORRECT, 74 KV_KEY_VALIDATE_WRONG 75 } kv_key_validate_status_t; 76 77 typedef uint16_t kv_key_id; 78 79 /** Represents the location in flash of a KV key. Provided in such a way that it can't be dereferenced, 80 * as flash is not directly addressable */ 81 typedef const void *kv_key_location; 82 83 /** Defines a set of conditions to match when searching through stores for keys */ 84 typedef struct { 85 kv_key_location location; /* (retained) location is out of context here */ 86 kv_key_id pattern; /* Pattern of bits matched against a key_id, after mask has been applied */ 87 kv_key_id mask; /* Mask is applied to a key id before matching pattern */ 88 kv_key_filter_state_t state; /* Include only keys of the specified state in search results */ 89 kv_key_filter_type_t type; /* Include only keys of the specified type in search results */ 90 } kv_key_filter_t; 91 92 /** KV store key header */ 93 typedef struct { 94 uint8_t magic; /* Magic number to indicate the start of the item */ 95 uint8_t valid; /* flag to indicate whether the value is valid. */ 96 uint16_t length; /* Length of the key_data field in bytes */ 97 uint8_t type; /* Normal (0xFF) or permanent (0x00) */ 98 uint8_t upgrade; /* Indicating whether upgradeable(not.0x00) */ 99 uint16_t key_id; /* The Key ID */ 100 uint16_t enc_key; /* Allows some customisation of the data AES key used, */ 101 /* 0x0 - key_data is plaintext, Others - key_data is encrypted */ 102 uint16_t version; /* Version of the key */ 103 uint32_t rnd; /* align the header to be 16bytes, random number */ 104 } kv_key_header_t; 105 106 /** A KV key handle, which provides both key header information and the location of key data in flash */ 107 typedef struct { 108 kv_key_header_t header; 109 kv_key_location key_location; /* Location in flash of the KV key */ 110 } kv_key_handle_t; 111 112 typedef struct { 113 kv_key_id key_id; 114 bool focre_write; 115 const uint8_t *kvalue; 116 uint32_t kvalue_length; 117 kv_attributes_t attributes; 118 } kv_key_details_t; 119 typedef struct { 120 uint32_t crypto_handle; 121 uint8_t *key_data_chunk; 122 uint8_t *compare_data_chunk; 123 } kv_helper_compare_key_data_info_t; 124 125 extern uint8_t g_nv_header_magic; 126 127 errcode_t kv_key_helper_copy_flash(uint32_t dest_location, uint32_t src_location, uint16_t length); 128 errcode_t kv_key_direct_write_flash(uint32_t dest, uint32_t length, const uint8_t *src); 129 errcode_t kv_key_direct_erase_flash(uint32_t dest, const uint32_t size); 130 errcode_t kv_key_write_flash(uint32_t dest, uint32_t length, const uint8_t *src); 131 errcode_t kv_key_erase_flash(uint32_t dest, const uint32_t size); 132 bool kv_key_is_erased(const kv_key_handle_t *key); 133 errcode_t kv_key_validate_integrity(kv_key_handle_t *key, bool ignor_invalid); 134 errcode_t kv_key_validation(kv_key_handle_t *key, bool ignor_invalid); 135 bool kv_key_is_valid(kv_key_handle_t *key); 136 errcode_t kv_key_does_filter_match(kv_key_handle_t *key, kv_key_filter_t *search_filter); 137 errcode_t kv_key_get_handle_from_location(kv_key_location key_location, kv_key_handle_t *key); 138 errcode_t kv_key_locations_in_same_page(kv_key_location first_key_location, kv_key_location second_key_location); 139 errcode_t kv_key_get_next_handle(kv_key_handle_t *key, kv_key_validate_status_t key_status); 140 kv_attributes_t kv_key_attributes(const kv_key_handle_t *key); 141 uint16_t kv_key_padded_data_length(kv_attributes_t attributes, uint16_t unpadded_length); 142 uint16_t kv_key_flash_size(kv_key_handle_t *key); 143 errcode_t kv_key_read_data(kv_key_handle_t *key, uint8_t *dest_location); 144 errcode_t kv_helper_compare_key_data(kv_key_handle_t *key, const uint8_t *compare_data, uint16_t compare_length); 145 void kv_key_build_from_new(kv_key_handle_t *key, const kv_key_details_t *new_key, kv_key_location key_location); 146 errcode_t kv_key_get_next_magic_position(kv_key_location key_location, kv_key_handle_t *key); 147 148 uint32_t kv_crc32_swap(uint32_t crc); 149 150 #ifdef __cplusplus 151 #if __cplusplus 152 } 153 #endif /* __cplusplus */ 154 #endif /* __cplusplus */ 155 156 #endif /* NV_KEY_H */ 157