Feature Usage

Firmware requirements:

Obtain the software packages:

In the current version, the verify lib, QCA lib, and QTA are open-sourced in the openEuler community. You can see the demos to learn how to use remote attestation APIs and develop remote attestation applications. To obtain, compile, and use the demos, perform the following steps.

1. Compile and deploy libteec.so.

   Obtain and compile the itrustee_client following the instructions in Obtaining the iTrustee Patch Package. Deploy libteec.so in the /usr/lib64 directory. Ensure that the /usr/lib64 directory has been added to the default search path of the system dynamic library.

2. Download the iTrustee SDK, which contains the QCA lib and QTA source code.

   https://gitee.com/openeuler/itrustee_sdk.git

   Code branch: master

   The iTrustee SDK contains the QCA lib and QTA source code. The code paths are as follows:

   QCA lib: itrustee_sdk/test/CA/libqca

   QTA: itrustee_sdk/test/TA/qta

3. Download and integrate the safety function library.

   https://gitee.com/openeuler/libboundscheck.git

   Code branch: master

   Integrate the safety function library into the iTrustee SDK.

   cp -rf libboundscheck/ itrustee_sdk/thirdparty/open_source/  # Replace the path with the actual one.

4. Compile and deploy the QCA lib and QTA.
   1. Compile and deploy the QCA lib.

      cd itrustee_sdk/test/CA/libqca   # Replace the path with the actual one.
      make
      cp output/libqca.so /usr/lib64 && ldconfig

      

      If the compilation is successful, the output/libqca.so dynamic library is generated. You need to deploy libqca.so into the default search path of the system dynamic library, for example, /usr/lib64.

   2. Compile and deploy the QTA.

      Similar to common TAs, a QTA requires a TA developer certificate issued by Huawei. For details, see Applying for a TA Developer Certificate in a Debugging Environment.

      After obtaining the TA developer certificate and the config binary file, deploy the TA private key and config binary file of the QTA to the following paths, for example:

      itrustee_sdk/build/signtools/signed_config/config

      itrustee_sdk/build/signtools/TA_cert/private_key.pem

      pip3 install pycryptodomex           # Install the dependency of the iTrustee SDK TA signature tool.
      cd itrustee_sdk/test/TA/qta    # Replace the path with the actual one.
      make
      cp e08f7eca-e875-440e-9ab0-5f381136c600.sec /vendor/bin

      

      If the QTA compilation is successful, the e08f7eca-e875-440e-9ab0-5f381136c600.sec file is generated and needs to be deployed into the /vendor/bin directory. This directory is specified by the QCA lib code and can be replaced with the actual one.

   

   The QTA is a privileged TA for remote attestation. The QTA UUID must be e08f7eca-e875-440e-9ab0-5f381136c600 and the QTA service name can be modified.

5. Download the Kunpeng security library to obtain the remote attestation demo.

   https://gitee.com/openeuler/kunpengsecl/tree/feature/tee-phase1

   Code branch: feature/tee-phase1

6. Set the QCA lib reference path of the RA Service.

   vim kunpengsecl/attestation/tee/demo/qca_demo/qcatools/qcatools.go  # Replace the path with the actual one.

   The following three key paths must be specified:

   • Search path of the external API header file of libqca.
   • Search path of the CA header file in the iTrustee SDK.
   • Link to the libqca.so and libteec.so dynamic libraries.

   

   The preceding figure is for reference only. Replace the paths with the actual ones.

   The RA Service demo needs to use #include <ra_client_api.h> to reference the external API header file of libqca, and add the #include <stdbool.h> and #include <stdlib.h> header files.

7. Compile the remote attestation demo.
   1. Prepare the compilation environment.

      yum install golang
      cd kunpengsecl/attestation/quick-scripts  # Replace the path with the actual one.
      bash prepare-build-env.sh

   2. Compile the libteeverifier dynamic library.

      cd kunpengsecl/attestation/tee/tverlib/verifier # Replace the path with the actual one.
      make
      cp -rf libteeverifier.so /usr/lib64
      ldconfig

   3. Compile the demo.

      cd kunpengsecl/attestation/tee/demo     # Replace the path with the actual one.
      make
      cp pkg/qcaserver /vendor/bin/ra_client_test

      

      If the compilation is successful, the pkg directory is generated. pkg/qcaserver indicates the RA Service, which needs to be deployed in the /vendor/bin directory and named ra_client_test. The RA Service deployment path and the executable file name are subject to the QTA code path. The QTA checks the load path of the CA (for example, RA Service) that initiates the remote attestation request. You can adjust the path as required.

8. Execute the remote attestation demo.
   1. Start the RA Service.

      cd /vendor/bin
      vim config.yaml    # Replace the content as required. The following is an example of config.yaml.
      /vendor/bin/ra_client_test

      By default, the RA Service loads the config.yaml configuration file from the current command execution path. The config.yaml file specifies the listening IP address and port of the RA Service and the remote attestation scenario. The current version supports remote attestation only when the AS service is not deployed, that is, scenario is set to 0.

      An example of config.yaml:

      qcaconfig:
        server: 127.0.0.1:40007
        scenario: 0

      The following figure shows the screenshot displayed after the RA Service is started properly.

      

      The system displays a message indicating that the RA Service successfully loads the configuration file, associates with the listening IP address and port, and registers the remote attestation key through the QCA lib API.

   2. Start the attester to initiate remote attestation.

      cd kunpengsecl/attestation/tee/demo/pkg/  # Replace the path with the actual path of the attester binary file generated in step 6.
      vim config.yaml      # Replace the content as required. The following is an example of config.yaml.
      vim basevalue.txt    # Specify the remote baseline measurement values of the TA.
      ./attester

      The remote attestation client attester communicates with the RA Service through a remote procedure call (RPC). In the config.yaml file, specify the IP address and port of the RA Service and the UUID of the TA to be measured.

      An example of config.yaml:

      attesterconfig:
        server: 127.0.0.1:40007
        basevalue: "./basevalue.txt"
        mspolicy: 1
        uuid: f68fd704-6eb1-4d14-b218-722850eb3ef0

      server: specifies the IP address and port of the RA Service.

      basevalue: file for storing baseline TA measurement values.

      mspolicy: remote measurement policy. The value 1 indicates that only the img-hash value is compared with the base value. The value 2 indicates that only the mem-hash value is compared with the base value. The value 3 indicates that both the img-hash and mem-hash values are compared with the base value.

      uuid: UUID of the TA to be measured. Replace it as the actual one.

      An example of basevalue.txt:

      f68fd704-6eb1-4d14-b218-722850eb3ef0 bda93201babc6ee96b60edd6b4104c0a5b2ab66f22b3e82a0fbe121c955755b2 319964db5bfad8ffd1b32abe7148f7681b1ef15f4bab8a20d377d9623feb3758

      The basevalue file stores the reference value records of the TA in hexadecimal character strings. Each basevalue record consists of three items: uuid, image-hash, and mem-hash. Items are separated by spaces, and records are separated by line breaks.

      Start the remote attestation client attester, as shown in the following figure:

      

      The RA Service displays a message indicating that the TA remote attestation report fails to be obtained:

      

      Run the tlogcat command to view the QTA error logs:

      

      The TA to be measured is not loaded, and the TA measurement report fails to be obtained. Load the TA and run the attester again. The following figure shows the running result:

      

      The measurement report for the target TA is obtained. After the report validity is confirmed, the real-time TA measurement values in the report are extracted and successfully matched with the baseline values in the basevalue file.

      When the iTrustee SDK is used to build a target TA, the baseline measurement values of the TA image and runtime memory (code segments and read-only data segments) are automatically calculated by running itrustee_sdk/build/signtools/get_ta_elf_hash.py. The results are recorded in the itrustee_sdk/build/signtools/hash_{TA-UUID}.txt file. For example, the content of hash_f68fd704-6eb1-4d14-b218-722850eb3ef0.txt is as follows:

      

      

      • To ensure that the attestation key is trusted, the Kunpeng security library uses Huawei's attestation identity key (AIK) level-2 public key certificate for the verification.
      • This section describes how to use the remote demo in the Kunpeng security library without the Attestation Service. For details about the remote attestation demo with the Attestation Service, see Kunpeng Security Library Remote Attestation Demo.