The security subsystem provides network device connectivity and authentication functions, relying on mbedtls for hardware random number generation and networking capabilities. Since each vendor's chip hardware and implementtaion methods for hardware random numbers differ, adapting the hardware random number interface is necessary.

Porting Guide

OpenHarmony provides an open-source third-party library for mbedtls located at //third_party/mbedtls. This library offers several methods for generating random numbers, including mbedtls_platform_entropy_poll, mbedtls_hardclock_poll, mbedtls_havege_poll, and mbedtls_hardware_poll. Vendors need to adapt the mbedtls_hardware_poll method based on their chip specifications.

Porting Example

1. Adding filesystem in config.json

   Path: vendor/MyVendorCompany/MyProduct/config.json

   Modify as follows:

   {
     "subsystem": "security",
     "components": [
       { "component": "hichainsdk", "features":[] },
       { "component": "huks", "features":[]}
     ]
   },
   

2. Configuring macros to enable hardware random number interface code

   Based on mbedtls compilation files, the configuration macro location is in MBEDTLS_CONFIG_FILE=<…/port/config/config_liteos_m.h>.

   Path: third_party/mbedtls/BUILD.gn

   if (ohos_kernel_type == "liteos_m") {
     defines += [
       "__unix__",
       "MBEDTLS_CONFIG_FILE=<../port/config/config_liteos_m.h>",
     ]
   }
   

   As shown in the code, two macros need to be configured: MBEDTLS_NO_PLATFORM_ENTROPY and MBEDTLS_ENTROPY_HARDWARE_ALT to compile the hardware random number related code.

   Path: third_party/mbedtls/library/entropy.c

   #if !defined(MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES)
   #if !defined(MBEDTLS_NO_PLATFORM_ENTROPY)
       mbedtls_entropy_add_source( ctx, mbedtls_platform_entropy_poll, NULL,
                                   MBEDTLS_ENTROPY_MIN_PLATFORM,
                                   MBEDTLS_ENTROPY_SOURCE_STRONG );
   #endif
   ......
   #if defined(MBEDTLS_ENTROPY_HARDWARE_ALT)
       mbedtls_entropy_add_source( ctx, mbedtls_hardware_poll, NULL,
                                   MBEDTLS_ENTROPY_MIN_HARDWARE,
                                   MBEDTLS_ENTROPY_SOURCE_STRONG );
   #endif
   ......
   #endif /* MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES */
   }
   

3. Adapting the hardware random number interface

   The interface definition is as follows:

   Path: third_party/mbedtls/include/mbedtls/entropy_poll.h

   int mbedtls_hardware_poll( void *p_context, unsigned char *p_output, size_t p_len, size_t *p_olen );
   

   Table 1 Security Subsystem Configuration Items

   Configuration Item	Description
   disable_huks_binary	Whether to compile HUKS source code. (1) Default: false, does not compile HUKS source. (2) Other values: true, compiles HUKS source.
   disable_authenticate	Whether to trim hichain authentication functionality. (1) Default: true, no trimming. (2) Other values: false, trims hichain authentication.
   huks_use_lite_storage	Whether to use lightweight storage. Devices without file system and only flash storage can use lightweight storage. (1) Default: true, uses lightweight storage. (2) Other values: false, does not use lightweight storage.
   huks_use_hardware_root_key	Whether to use hardware root key. When the device has hardware root key capability, it needs to adapt the hardware root key solution based on its own capability; the RKC solution provided by HUKS is only a simulation. (1) Default: false, default has no hardware root key. (2) Other values: true, when device has hardware root key related capability, it should adapt itself.
   huks_config_file	Whether to use HUKS default configuration file. (1) Default: "": uses HUKS default configuration file hks_config.h. (2) Other files: products can independently select which features to support from HUKS supported capability set.

   Note: When adding the sceurity subsystem, you can directly select security subsystem features by configuring features.

   {
     "subsystem": "security",
     "components": [
       { "component": "hichainsdk", "features":[] },
       { "component": "huks", "features":
         [
           "disable_huks_binary = false",
           "disable_authenticate = false"
         ]
       }
     ]
   },