Keybox

Due to limited efuse space, Tina supports the Keybox Secure Storage feature by default. This document describes how to customize and burn keyboxes, as well as read them.

---

1. Firmware Configuration

Prerequisite: Secure firmware is required. For secure firmware details, refer to 14-Secure Boot.

1.1 Customize Keybox List

U-Boot loads keys into Secure OS based on the keybox_list environment variable. Configure this variable in the env.cfg file using comma-separated key names.

Example: Add a custom key name xie:

--- a/device/config/chips/h618/configs/default/env.cfg
+++ b/device/config/chips/h618/configs/default/env.cfg
@@ -13,7 +13,7 @@ mac=
 wifi_mac=
 bt_mac=
 specialstr=
-keybox_list=hdcpkey,widevine
+keybox_list=hdcpkey,widevine,xie
 #set kernel cmdline if boot.img or recovery.img has no cmdline we will use this
 setargs_nand=setenv bootargs earlyprintk=${earlyprintk} initcall_debug=${initcall_debug} console=${console} loglevel=${loglevel} root=${nand_root} init=${init} partitions=${partitions} cma=${cma} snum=${snum} mac_addr=${mac} wifi_mac=${wifi_mac} bt_mac=${bt_mac} selinux=${selinux} specialstr=${specialstr} gpt=1
 setargs_mmc=setenv  bootargs earlyprintk=${earlyprintk} initcall_debug=${initcall_debug} console=${console} loglevel=${loglevel} root=${mmc_root} rootwait init=${init} partitions=${partitions} cma=${cma} snum=${snum} mac_addr=${mac} wifi_mac=${wifi_mac} bt_mac=${bt_mac} selinux=${selinux} specialstr=${specialstr} gpt=1

---

1.2 Keybox Configuration Reading

Keybox reading uses Allwinner-provided APIs. Tina includes demo implementations for these APIs. Keybox access requires TA/CA interaction.

• CA: A Linux user-space application dependent on optee-client libraries.

• TA: A secure application compiled using TA dev-kit.

1.2.1 TA/CA Compilation Configuration

1. Run kernel configuration:

   $ make menuconfig

2. Enable the following options:

   Tina Configuration
   └─> Security ‑‑‑>
       └─> OPTEE ‑‑‑>
           └─> -*- optee-client............................... optee-client 
           └─> <*> optee-efuse-read................... OPTEE efuse read demo
           └─> <*> optee-helloworld....................... OPTEE Hello World
           └─> -*- optee-os-dev-kit...................... optee-os-dev-kit  

   optee-efuse-read: Example for keybox reading. optee-helloworld: Example to verify TA/CA environment.

3. Verify changes:

   $ git diff target/allwinner/h618-p2/defconfig

   diff --git a/target/allwinner/h618-p2/defconfig b/target/allwinner/h618-p2/defconfig
   index c6c47b5f4..d3b2737eb 100755
   --- a/target/allwinner/h618-p2/defconfig
   +++ b/target/allwinner/h618-p2/defconfig
   @@ -4232,10 +4232,10 @@ CONFIG_PACKAGE_wpa_supplicant_rtl=y
    #
    # CONFIG_PACKAGE_optee-aes-hmac is not set
    # CONFIG_PACKAGE_optee-base64 is not set
   -# CONFIG_PACKAGE_optee-client is not set
   -# CONFIG_PACKAGE_optee-efuse-read is not set
   -# CONFIG_PACKAGE_optee-helloworld is not set
   -# CONFIG_PACKAGE_optee-os-dev-kit is not set
   +CONFIG_PACKAGE_optee-client=y
   +CONFIG_PACKAGE_optee-efuse-read=y
   +CONFIG_PACKAGE_optee-helloworld=y
   +CONFIG_PACKAGE_optee-os-dev-kit=y
    # CONFIG_PACKAGE_optee-rotpk is not set
    # CONFIG_PACKAGE_optee-secure-storage is not set
    # CONFIG_PACKAGE_optee-test is not set

4. Add platform-specific dev-kit:

   $ cd package/security/optee-os-dev-kit/dev_kit/
   $ cp -rp arm-plat-sun50iw1p1 arm-plat-sun50iw9p1

1.2.2 Modifications for optee-efuse-read Demo

Add debug prints for keybox buffer:

--- a/package/security/optee-efuse-read/src/ta/efuse_read_demo_ta.c
+++ b/package/security/optee-efuse-read/src/ta/efuse_read_demo_ta.c
@@ -96,13 +96,16 @@ TEE_Result TA_InvokeCommandEntryPoint(void *pSessionContext,
                        memcpy(keyname,"testkey",sizeof("testkey"));
                        keyname[49]=0;
                }
-               i = utee_sunxi_keybox((const char*)keyname, rdbuf, 16);
+               printf("keyname: %s \n",keyname);
+               i = utee_sunxi_keybox((const char*)keyname, rdbuf, 128);
                if (i != TEE_SUCCESS) {
                        printf("read key:%s from keybox failed with:%d\n",keyname,i);
                        return i;
                } else {
-                       i = utee_sunxi_read_efuse("oem_secure", &rd_len,
-                                                 rdbuf + 16);
+                       printf("keybox:\n");
+                       dump(rdbuf, 128);
+                       i = utee_sunxi_read_efuse("widevine", &rd_len,
+                                                 rdbuf + 128);
                        if (i == TEE_SUCCESS) {
                                printf("read result:\n");
                                dump(rdbuf, rd_len + 16);

dump is a built-in hex print function. 128 corresponds to the key length.

1.2.3 Allwinner-Specific APIs

• utee_sunxi_keybox

  TEE_Result utee_sunxi_keybox(const char *keyname, uint8_t *out_buf, uint32_t size);

  Purpose: Read keybox data by name. Parameters:

  • keyname: Key name (must match entries in keybox_list).

  • out_buf: Output buffer (size ≥ size).

  • size: Data length to read. Return: 0 (success), -1 (failure).

• utee_sunxi_read_efuse

  TEE_Result utee_sunxi_read_efuse(const char *keyname, uint8_t *result_len, uint8_t *rd_buf);

  Purpose: Read efuse data. Parameters:

  • keyname: Key name.

  • result_len: Output data length.

  • rd_buf: Output buffer. Return: 0 (success), others (failure).

• utee_sunxi_write_efuse

  TEE_Result utee_sunxi_write_efuse(const char* keyname, uint8_t write_len, uint8_t *wr_buf);

  Purpose: Burn data to efuse. Parameters:

  • keyname: Key name.

  • write_len: Data length (bytes).

  • wr_buf: Data buffer. Return: 0 (success), others (failure).

---

1.3 Compile Secure Firmware

1. Enable burn_key in sys_config.fex:

   [target]
   burn_key = 1

   

   image-20241122101659346
2. Build firmware:

   $ source build/envsetup.sh
   $ lunch apollo_p2-userdebug
   $ pack -sv

   Output: longan/out/h618_android12_p2_uart0_secure_secure_v0.img (v0 is the default version number).

---

1.4 Burn Verification

1. Check keybox_list in U-Boot:

   => printenv
   keybox_list=hdcpkey,widevine,xie

2. Verify TA/CA functionality:

   # tee-supplicant &
   # hello_world_na 
   NA:init context
   NA:open session
   TA:creatyentry!
   TA:open session!
   NA:allocate memory
   NA:invoke command
   TA:rec cmd 0x210
   TA:hello world!
   NA:finish with 0

---

2. Burn Keybox

Use the DragonSN tool to burn keyboxes via USB.

1. Open DragonSN:

2. Configure key settings:

   • Select Key Configuration:

   

   image-20250514093013109

   • Add key entry (xie in this example):

3. Select key file and burn options:

   • Enable Erase Before Burn and Power Off After Burn (for production).

   • Select key file:

4. Start burning:

5. Completion:

---

3. Read Keybox

1. U-Boot Verification:

   => pst read
   [259.435]name in map xie
   [259.450]1 data:
   48 39 25 17 00 00 00 00 78 69 65 00 00 00 00 00 
   ... (truncated)

2. System-Level Read:

   # tee-supplicant &
   # efuse_read_demo_na -ext_key xie

   Output:

   NA:init context
   NA:open session
   TA:creatyentry!
   TA:open session!
   NA:allocate memoryTA:rec cmd 0x220
   
   NA:invoke command
   keyname: xie 
   keybox:
   0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 
   ... (truncated)

   Compare the output with your burned key for verification.