1 /* 2 * Copyright (C) 2022 Huawei Technologies Co., Ltd. 3 * Licensed under the Mulan PSL v2. 4 * You can use this software according to the terms and conditions of the Mulan PSL v2. 5 * You may obtain a copy of Mulan PSL v2 at: 6 * http://license.coscl.org.cn/MulanPSL2 7 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR 8 * IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR 9 * PURPOSE. 10 * See the Mulan PSL v2 for more details. 11 */ 12 13 #ifndef TASK_TUI_GP_API_H 14 #define TASK_TUI_GP_API_H 15 16 /** 17 * @addtogroup TeeTrusted 18 * @{ 19 * 20 * @brief TEE(Trusted Excution Environment) API. 21 * Provides security capability APIs such as trusted storage, encryption and decryption, 22 * and trusted time for trusted application development. 23 * 24 * @since 12 25 */ 26 27 /** 28 * @file tee_tui_gp_api.h 29 * 30 * @brief Provides APIs for operating big integers. 31 * 32 * @library NA 33 * @kit TEE Kit 34 * @syscap SystemCapability.Tee.TeeClient 35 * @since 12 36 * @version 1.0 37 */ 38 39 #include <stdbool.h> 40 #include <stdint.h> 41 #include <stdlib.h> 42 #include <tee_defines.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 #define TEE_TUI_NUMBER_BUTTON_TYPES 0x00000006 49 #define TEE_STORAGE_PRIVATE 0x00000001 50 #define DEFAULT_MAX_ENTRY_FIELDS 3 51 52 #define TUI_EXIT 8 53 54 /** 55 * @brief Enumerates the modes supported when displaying characters within an input entry field. 56 * 57 * @since 12 58 */ 59 typedef enum { 60 /** Never visible, displayed as '*'. */ 61 TEE_TUI_HIDDEN_MODE = 0, 62 /** Always visible. */ 63 TEE_TUI_CLEAR_MODE, 64 /** Visible then hidden. */ 65 TEE_TUI_TEMPORARY_CLEAR_MODE 66 } TEE_TUIEntryFieldMode; 67 68 /** 69 * @brief Enumerates the input types supported of the TUI entry field. 70 * 71 * @since 12 72 */ 73 typedef enum { 74 /** When the field accepts only digits as inputs. */ 75 TEE_TUI_NUMERICAL = 0, 76 /** When the field accepts characters and digits as inputs. */ 77 TEE_TUI_ALPHANUMERICAL, 78 } TEE_TUIEntryFieldType; 79 80 /** 81 * @brief Enumerates the TUI screen orientation. 82 * @attention Currently {@code TEE_TUI_LANDSCAPE} is not supported. 83 * 84 * @since 12 85 */ 86 typedef enum { 87 /** Displayed as a portrait, i.e. vertically. */ 88 TEE_TUI_PORTRAIT = 0, 89 /** Displayed as a landscape, i.e. horizontally. */ 90 TEE_TUI_LANDSCAPE, 91 } TEE_TUIScreenOrientation; 92 93 /** 94 * @brief Enumerates the types of the button. 95 * 96 * @since 12 97 */ 98 typedef enum { 99 /** Used to delete the previous input digit. */ 100 TEE_TUI_CORRECTION = 0, 101 /** Exits the interface. */ 102 TEE_TUI_OK, 103 /** Cancels the operation and exits the interface. */ 104 TEE_TUI_CANCEL, 105 /** Used to trigger PIN verifcation and exit the interface.*/ 106 TEE_TUI_VALIDATE, 107 /** Exit the current interface and ask the TA to display the previous interface. */ 108 TEE_TUI_PREVIOUS, 109 /** Exit the current interface and ask the TA to display the next interface. */ 110 TEE_TUI_NEXT, 111 } TEE_TUIButtonType; 112 113 /** 114 * @brief Enumerates source of the uesd image. 115 * 116 * @since 12 117 */ 118 typedef enum { 119 /** No picture provided in the input. */ 120 TEE_TUI_NO_SOURCE = 0, 121 /** The picture provided as a memory pointer. */ 122 TEE_TUI_REF_SOURCE, 123 /** The picture provided by an object in the secure storage. */ 124 TEE_TUI_OBJECT_SOURCE, 125 /** The picture provided as a file. */ 126 TEE_TUI_FILE_SOURCE = 0x8001 127 } TEE_TUIImageSource; 128 129 /** 130 * @brief Represents the image in PNG format. 131 * 132 * @since 12 133 */ 134 typedef struct { 135 TEE_TUIImageSource source; 136 struct { 137 void *image; 138 size_t imageLength; 139 } ref; 140 struct { 141 uint32_t storageID; 142 void *objectID; 143 size_t objectIDLen; 144 } object; 145 /** Represents the number of pixels of the width of the image. */ 146 uint32_t width; 147 /** Represents the number of pixels of the height of the image. */ 148 uint32_t height; 149 } TEE_TUIImage; 150 151 /** 152 * @brief Enumerates the GP color index. 153 * 154 * @since 12 155 */ 156 enum gp_color_idx { 157 /** Red color index. */ 158 RED_IDX = 0, 159 /** Green color index. */ 160 GREEN_IDX = 1, 161 /** Blue color index. */ 162 BLUE_IDX = 2, 163 /** RGB color index. */ 164 RGB_COLOR_IDX = 3, 165 }; 166 167 /** 168 * @brief Represents the label for TA branding/message, generally on the top of screen. 169 * 170 * @since 12 171 */ 172 typedef struct { 173 /** It's the string to put in the label area, which can be NULL. */ 174 char *text; 175 /** X-coordinate of the upper left corner of the text information. */ 176 uint32_t textXOffset; 177 /** Y-coordinate of the upper left corner of the text information. */ 178 uint32_t textYOffset; 179 /** RGB color used for displaying the text information. */ 180 uint8_t textColor[RGB_COLOR_IDX]; 181 /** The image is placed in the label area. */ 182 TEE_TUIImage image; 183 /** X-coordinate of the upper left corner of the image to be displayed. */ 184 uint32_t imageXOffset; 185 /** Y-coordinate of the upper left corner of the image to be displayed. */ 186 uint32_t imageYOffset; 187 } TEE_TUIScreenLabel; 188 189 /** 190 * @brief Represents the content displayed on a button. 191 * 192 * @since 12 193 */ 194 typedef struct { 195 /** It's the string to associate with the button, which can be NULL. */ 196 char *text; 197 /** The image to associate with the button. */ 198 TEE_TUIImage image; 199 } TEE_TUIButton; 200 201 /** 202 * @brief Represents the configuration about the TUI screen. 203 * 204 * @since 12 205 */ 206 typedef struct { 207 /** The requested screen orientation. */ 208 TEE_TUIScreenOrientation screenOrientation; 209 /** The specifies label of the screen.*/ 210 TEE_TUIScreenLabel label; 211 /** Customizes the buttons compared to the default. */ 212 TEE_TUIButton *buttons[TEE_TUI_NUMBER_BUTTON_TYPES]; 213 /** Specifes which buttons to be displayed. */ 214 bool requestedButtons[TEE_TUI_NUMBER_BUTTON_TYPES]; 215 } TEE_TUIScreenConfiguration; 216 217 /** 218 * @brief Represents the information about a TUI screen button. 219 * @attention The {@code buttonTextCustom} and {@code buttonImageCustom} cannot be set to true at the same time. 220 * 221 * @since 12 222 */ 223 typedef struct { 224 /** Defaut label value of the button text. If the value is NULL means the parameter is unavailable. */ 225 const char *buttonText; 226 /** The pixel width of the button. 227 * If the text or image on the button cannot be customized, the value is <b>0</b>. 228 */ 229 uint32_t buttonWidth; 230 /** The pixel height of the button. 231 * If the text or image on the button cannot be customized, the value is <b>0</b>. 232 */ 233 uint32_t buttonHeight; 234 /** If the text on the button cannot be customized, the value is true. */ 235 bool buttonTextCustom; 236 /** If the image on the button cannot be customized, the value is true. */ 237 bool buttonImageCustom; 238 } TEE_TUIScreenButtonInfo; 239 240 /** 241 * @brief Represents the information displayed on the TUI. 242 * 243 * @since 12 244 */ 245 typedef struct { 246 /** Available grayscale. */ 247 uint32_t grayscaleBitsDepth; 248 /** Available red depth level. */ 249 uint32_t redBitsDepth; 250 /** Available green depth level. */ 251 uint32_t greenBitsDepth; 252 /** Available blue depth level. */ 253 uint32_t blueBitsDepth; 254 /** Indicates the number of pixels per inch in the width direction. */ 255 uint32_t widthInch; 256 /** Indicates the number of pixels per inch in the height direction. */ 257 uint32_t heightInch; 258 /** Indicates the maximum number of entries that can be displayed on the TUI. */ 259 uint32_t maxEntryFields; 260 /** Indicates the pixel width of the input region label. */ 261 uint32_t entryFieldLabelWidth; 262 /** Indicates the pixel height of the input region label. */ 263 uint32_t entryFieldLabelHeight; 264 /** Indicates the maximum number of characters that can be entered in the entry field. */ 265 uint32_t maxEntryFieldLength; 266 /** RGB value of the default label canvas. */ 267 uint8_t labelColor[RGB_COLOR_IDX]; 268 /** Indicates the pixel width of the label canvas. */ 269 uint32_t labelWidth; 270 /** Indicates the pixel height of the label canvas. */ 271 uint32_t labelHeight; 272 /** Indicates the information of the buttons on the interface. */ 273 TEE_TUIScreenButtonInfo buttonInfo[TEE_TUI_NUMBER_BUTTON_TYPES]; 274 } TEE_TUIScreenInfo; 275 276 /** 277 * @brief Represents the information in an entry field that requires user input. 278 * 279 * @since 12 280 */ 281 typedef struct { 282 /** Indicates the label of the entry field. */ 283 char *label; 284 /** Indicates the mode used to display characters. */ 285 TEE_TUIEntryFieldMode mode; 286 /** Indicates the type of the characters can be entered in the entry field. */ 287 TEE_TUIEntryFieldType type; 288 /** The minimum number of characters to be entered. */ 289 uint32_t minExpectedLength; 290 /** The maximum number of characters to be entered. */ 291 uint32_t maxExpectedLength; 292 /** Contains the content entered by user. */ 293 char *buffer; 294 /** Indicates the length of the buffer. */ 295 size_t bufferLength; 296 } TEE_TUIEntryField; 297 298 /** 299 * @brief Initializing the TUI resources. 300 * 301 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 302 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 303 * Returns {@code TEE_ERROR_NOT_SUPPORTED} if the device is not support TUI. 304 * Returns {@code TEE_ERROR_BUSY} if the TUI resources cannot be reserved. 305 * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the system ran out of the resources. 306 * 307 * @since 12 308 * @version 1.0 309 */ 310 TEE_Result TEE_TUIInitSession(void); 311 312 313 /** 314 * @brief Releases TUI resources previously acquired. 315 * 316 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 317 * Returns {@code TEE_ERROR_BAD_STATE} if the current TA is not within a TUI session initially 318 * started by a successful call to {@code TEE_TUIInitSession}. 319 * Returns {@code TEE_ERROR_BUSY} if the TUI resources currently are in use. 320 * 321 * @since 12 322 * @version 1.0 323 */ 324 TEE_Result TEE_TUICloseSession(void); 325 326 /** 327 * @brief Allows a TA to check whether a given text can be rendered by the current implementation and 328 * retrieves information about the size and width that is needed to render it. 329 * 330 * @param text Indicates the string to be checked. 331 * @param width Indicates the width in pixels needed to render the text. 332 * @param height Indicates the height in pixels needed to render the text. 333 * @param last_index Indicates the last character that has been checked 334 * 335 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 336 * Returns {@code TEE_ERROR_NOT_SUPPORTED} if at least one of the characters present 337 * in the text string cannot be rendered. 338 * 339 * @since 12 340 * @version 1.0 341 */ 342 TEE_Result TEE_TUICheckTextFormat(const char *text, uint32_t *width, uint32_t *height, uint32_t *last_index); 343 344 /** 345 * @brief Retrieves information about the screen depending on its orientation and 346 * the number of required entry fields. 347 * 348 * @param screenOrientation Defines for which orientation screen information is requested. 349 * @param nbEntryFields Indicates the number of the requested entry fields. 350 * @param screenInfo Indicates the information on the requested screen for a given orientation. 351 * 352 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 353 * Returns {@code TEE_ERROR_NOT_SUPPORTED} if the number of entry fields is not supported. 354 * 355 * @since 12 356 * @version 1.0 357 */ 358 TEE_Result TEE_TUIGetScreenInfo(TEE_TUIScreenOrientation screenOrientation, 359 uint32_t nbEntryFields, 360 TEE_TUIScreenInfo *screenInfo); 361 /** 362 * @brief Display a TUI screen. 363 * 364 * @param screenConfiguration Indicates the configuration of the labels and optional buttons on the display interface. 365 * @param closeTUISession If the value is true, the TUI session will automatically closed when exiting the function. 366 * @param entryFields Indicates the information of entry field. 367 * @param entryFieldCount Indicates the count of the entry fields. 368 * @param selectedButton Indicates which button has been selected by the user to exit the TUI screen. 369 * 370 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 371 * Returns {@code TEE_ERROR_OUT_OF_MEMORY} if the system ran out of the resources. 372 * Returns {@code TEE_ERROR_ITEM_NOT_FOUND} if at least one image provided by the TA refers to a storage 373 * denoted by a storageID which dose not exist or if the corresponding object identifier cannot be found in the storage. 374 * Returns {@code TEE_ERROR_ACCESS_CONFLICT} if at least one image provided by the TA refers to a data 375 * object in the trusted storage and an access right conflict was detected while opening the object. 376 * Returns {@code TEE_ERROR_BAD_FORMAT} if at least one input image is not compliant with PNG format. 377 * Returns {@code TEE_ERROR_BAD_STATE} if the current TA is not within a TUI session 378 * initially started by a successful call to {@code TEE_TUIInitSession}. 379 * Returns {@code TEE_ERROR_BUSY} if the TUI resources are currently in use, i.e. a TUI screen is displayed. 380 * Returns {@code TEE_ERROR_CANCEL} if the operation has been cancelled while a TUI screen is currently 381 * displayed. 382 * Returns {@code TEE_ERROR_EXTERNAL_CANCEL} if the operation has been cancelled by an external event which 383 * occurred in the REE while a TUI screen is currently displayed. 384 * 385 * @since 12 386 * @version 1.0 387 */ 388 TEE_Result TEE_TUIDisplayScreen(TEE_TUIScreenConfiguration *screenConfiguration, 389 bool closeTUISession, 390 TEE_TUIEntryField *entryFields, 391 uint32_t entryFieldCount, 392 TEE_TUIButtonType *selectedButton); 393 394 /** 395 * @brief Fringerprint identification port. 396 * 397 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 398 * Returns {@code TEE_ERROR_NOT_SUPPORTED} if the device is not support TUI. 399 * 400 * @since 12 401 * @version 1.0 402 */ 403 TEE_Result TEE_TUINotify_fp(void); 404 405 /** 406 * @brief Set the Chinese character encoding. The system supports UTF-8 by default. 407 * 408 * @param type Indicates the encoding type. The value 1 indicates GBK. Other values are not supported. 409 * 410 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 411 * Returns {@code TEE_ERROR_NOT_SUPPORTED} if the device is not support this function. 412 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 413 * 414 * @since 12 415 * @version 1.0 416 */ 417 TEE_Result TEE_TUISetInfo(int32_t type); 418 419 /** 420 * @brief Send message to TUI. 421 * 422 * @param type Indicates the messages send to the TUI. Only support {@code TUI_EXIT}. 423 * 424 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 425 * Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect. 426 * 427 * @since 12 428 * @version 1.0 429 */ 430 TEE_Result TEE_TUISendEvent(int32_t type); 431 432 /** 433 * @brief Setting the TUI background image. 434 * 435 * @param label Configure the background image information in the label variable. 436 * The image must be a PNG image in array format. 437 * @param len Indicates the label size. 438 * 439 * @return Returns {@code TEE_SUCCESS} if the operation is successful. 440 * Returns {@code TEE_ERROR_GENERIC} if input parameter is incorrect. 441 * Returns {@code TEE_ERROR_ACCESS_DENIED} if the permission verification failed. 442 * 443 * @since 12 444 * @version 1.0 445 */ 446 TEE_Result TEE_TUISetLabel(TEE_TUIScreenLabel *label, uint32_t len); 447 #ifdef __cplusplus 448 } 449 #endif 450 /** @} */ 451 #endif