1 /* 2 * Copyright (C) 2021 The Android Open Source Project 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 #pragma once 18 19 #include <arch/defines.h> 20 #include <lk/compiler.h> 21 #include <stdint.h> 22 23 #define HWAES_PORT "com.android.trusty.hwaes" 24 #define AES_KEY_MAX_SIZE 32 25 #define AES_BLOCK_SIZE 16 26 #define HWAES_MAX_NUM_HANDLES 8 27 #define HWAES_MAX_MSG_SIZE 0x1000 28 #define HWAES_INVALID_INDEX UINT32_MAX 29 30 /* For input buffers it is enough to align by AES_BLOCK_SIZE. */ 31 #define HWAES_TEXT_IN_BUF_ALIGNMENT AES_BLOCK_SIZE 32 33 /* For output buffers it should be also CACHE_LINE aligned 34 * to avoid cache issues in prepare_dma. 35 */ 36 #define HWAES_TEXT_OUT_BUF_ALIGNMENT CACHE_LINE 37 38 /* 39 * The number of parts on tipc request message: 40 * hwaes_req, hwaes_aes_req, array of hwaes_shm_desc, 41 * and input payloads for key, iv, aad, aad_padd, text_in, text_in_padd, tag_in. 42 */ 43 #define TIPC_REQ_MSG_PARTS (1 + 1 + 1 + 7) 44 45 /* 46 * The number of parts on tipc response message: 47 * hwaes_resp and input payloads for text_out, test_out_padd, tag_out. 48 */ 49 #define TIPC_RESP_MSG_PARTS (1 + 3) 50 51 /* 52 * The max number of TIPC_REQ_MSG_PARTS and TIPC_RESP_MSG_PARTS 53 */ 54 #if TIPC_REQ_MSG_PARTS > TIPC_RESP_MSG_PARTS 55 #define TIPC_MAX_MSG_PARTS TIPC_REQ_MSG_PARTS 56 #else 57 #define TIPC_MAX_MSG_PARTS TIPC_RESP_MSG_PARTS 58 #endif 59 60 /** 61 * enum hwaes_mode - mode types for hwaes 62 * @HWAES_ECB_MODE: ECB mode. 63 * @HWAES_CBC_MODE: CBC mode. 64 * @HWAES_CBC_CTS_MODE: CBC mode with ciphertext stealing (CTS). 65 * @HWAES_CTR_MODE: CTR mode. 66 * @HWAES_GCM_MODE: GCM mode. 67 */ 68 enum hwaes_mode { 69 HWAES_ECB_MODE = 0, 70 HWAES_CBC_MODE = 1, 71 HWAES_CBC_CTS_MODE = 2, 72 HWAES_CTR_MODE = 3, 73 HWAES_GCM_MODE = 4, 74 }; 75 76 /** 77 * enum hwaes_padding - padding types for hwaes 78 * @HWAES_NO_PADDING: No padding. 79 * @HWAES_PKCS_PADDING: PKCS padding. 80 * @HWAES_CTS_PADDING: Ciphertext stealing (CTS) padding. 81 */ 82 enum hwaes_padding { 83 HWAES_NO_PADDING = 0, 84 HWAES_PKCS_PADDING = 1, 85 HWAES_CTS_PADDING = 2, 86 }; 87 88 /** 89 * enum hwaes_key_type - key types for hwaes 90 * @HWAES_PLAINTEXT_KEY: Plaintext key, directly usable by hardware. 91 * @HWAES_OPAQUE_HANDLE: Opaque handle to a key from hwkey service. 92 * 93 * Opaque handles are created by the hwkey service and provide proxied access to 94 * key material that is not directly exposed to the client. The hwaes service 95 * will fetch the real key from hwkey when performing a cyptographic operation 96 * on behalf of the client. 97 */ 98 enum hwaes_key_type { 99 HWAES_PLAINTEXT_KEY = 0, 100 HWAES_OPAQUE_HANDLE = 1, 101 }; 102 103 /** 104 * enum hwaes_cmd - command identifiers for hwaes 105 * @HWAES_RESP_BIT: Response bit set as part of response. 106 * @HWAES_REQ_SHIFT: Number of bits used by response bit. 107 * @HWAES_AES: Command to run plain encryption. 108 */ 109 enum hwaes_cmd { 110 HWAES_RESP_BIT = 1, 111 HWAES_REQ_SHIFT = 1, 112 113 HWAES_AES = (1 << HWAES_REQ_SHIFT), 114 }; 115 116 /** 117 * enum hwaes_err - error codes for hwaes protocol 118 * @HWAES_NO_ERROR: All OK. 119 * @HWAES_ERR_GENERIC: Unknown error. Can occur when there's an 120 * internal server error, e.g. the server runs out 121 * of memory or is in a bad state. 122 * @HWAES_ERR_INVALID_ARGS: Arguments are invalid. 123 * If padding is not enabled, the unaligned data 124 * length will also cause this error code. 125 * @HWAES_ERR_IO: Protocol error between client lib and server. 126 * @HWAES_ERR_BAD_HANDLE: Fails to map the shared memory through the 127 * handle. 128 * @HWAES_ERR_NOT_IMPLEMENTED: Requested command or specified parameter is not 129 * implemented. 130 */ 131 enum hwaes_err { 132 HWAES_NO_ERROR = 0, 133 HWAES_ERR_GENERIC = 1, 134 HWAES_ERR_INVALID_ARGS = 2, 135 HWAES_ERR_IO = 3, 136 HWAES_ERR_BAD_HANDLE = 4, 137 HWAES_ERR_NOT_IMPLEMENTED = 5, 138 }; 139 140 /** 141 * struct hwaes_data_desc - data descriptor for the data transferred between 142 * client and server. 143 * @offset: The offset of the data. 144 * If the data is transferred through tipc message, it's offset from 145 * the of start of the tipc message. The offset needs to follow the 146 * order of entries in &struct hwaes_aes_req. No padding is allowed 147 * between entries. 148 * Otherwise, it's the offset from the start of the shared memory, 149 * whereby the data is transferred between client and server. 150 * @len: The length of the data. 151 * @shm_idx: The shm_idx is HWAES_INVALID_INDEX if the data is transferred 152 * through tipc message. 153 * Otherwise, it's the index of shared memory handle info array. 154 * @reserved: Reserved to make 64 bit alignment, must be 0. 155 */ 156 struct hwaes_data_desc { 157 uint64_t offset; 158 uint64_t len; 159 uint32_t shm_idx; 160 uint32_t reserved; 161 }; 162 STATIC_ASSERT(sizeof(struct hwaes_data_desc) == 8 + 8 + 4 + 4); 163 164 /** 165 * struct hwaes_shm_desc - shared memory descriptor 166 * @size: The size of the shared memory. 167 * @write: Flag to indicate whether the shared memory is writeable (value 1) 168 * or not (value 0). 169 * @reserved: Reserved to make 64 bit alignment, must be 0. 170 */ 171 struct hwaes_shm_desc { 172 uint64_t size; 173 uint32_t write; 174 uint32_t reserved; 175 }; 176 STATIC_ASSERT(sizeof(struct hwaes_shm_desc) == 8 + 4 + 4); 177 178 /** 179 * struct hwaes_req - request structure for hwaes 180 * @cmd: Command identifier. 181 * @reserved: Reserved to make 64 bit alignment, must be 0. 182 */ 183 struct hwaes_req { 184 uint32_t cmd; 185 uint32_t reserved; 186 }; 187 STATIC_ASSERT(sizeof(struct hwaes_req) == 4 + 4); 188 189 /** 190 * struct hwaes_resp - response structure for hwaes 191 * @cmd: Command identifier. 192 * @result: Operation result, one of enum hwaes_err. 193 */ 194 struct hwaes_resp { 195 uint32_t cmd; 196 uint32_t result; 197 }; 198 STATIC_ASSERT(sizeof(struct hwaes_resp) == 4 + 4); 199 200 /** 201 * struct hwaes_aes_req - request header for HWAES_AES command 202 * @key: The data descriptor for key. 203 * @iv: The data descriptor for IV. 204 * @aad: The data descriptor for AAD. 205 * @text_in: The data descriptor for input text. 206 * @tag_in: The data descriptor for input tag 207 * @text_out: The data descriptor for output text. 208 * @tag_out: The data descriptor for output tag. 209 * @key_type: The key_type, one of instances &enum hwaes_key_type. 210 * @padding: The padding type, one of instances &enum hwaes_padding. 211 * @mode: The AES mode, one of instances &enum hwaes_mode. 212 * @num_handles: The number of handles to shared memory. 213 * These handles are transferred from the client to the server. 214 * @encrypt: Flag for encryption (value 1) or decryption (value 0). 215 * @reserved: Reserved to make 64 bit alignment, must be 0. 216 * 217 * A array of shared memory descriptor follows this header in tipc message. 218 * The length of the shm_desc array is equal to num_handles. 219 * The order of each &struct hwaes_data_desc entry is the same as the 220 * corresponding data in the tipc message. 221 */ 222 struct hwaes_aes_req { 223 struct hwaes_data_desc key; 224 struct hwaes_data_desc iv; 225 struct hwaes_data_desc aad; 226 struct hwaes_data_desc text_in; 227 struct hwaes_data_desc tag_in; 228 struct hwaes_data_desc text_out; 229 struct hwaes_data_desc tag_out; 230 uint32_t key_type; 231 uint32_t padding; 232 uint32_t mode; 233 uint32_t num_handles; 234 uint32_t encrypt; 235 uint32_t reserved; 236 }; 237 STATIC_ASSERT(sizeof(struct hwaes_aes_req) == 238 sizeof(struct hwaes_data_desc) * 7 + 4 * 6); 239