Getting Started with QingTian Enclave

This section guides you through the process of understanding and using QingTian Enclave features. It shows you how to launch a parent instance, build a QingTian Enclave image file, query a running QingTian Enclave instance, and stop a QingTian Enclave instance.

Purchase an ECS and use it as the parent instance of QingTian Enclave. Select a Linux image for the OS and select Enclave.
For details, see Purchasing an ECS in Custom Config Mode. Huawei Cloud EulerOS 2.0 is recommended.
Connect to the parent instance of QingTian Enclave. For details, see Login Overview (Linux).
Configure the parent instance of QingTian Enclave.
- If you select the Huawei Cloud EulerOS 2.0 image:
  1. Install the qt CLI tool and required peripheral components in the parent instance.
    Install python modules required by qt CLI. For details, see Installation of the qt CLI.
```
yum install qt-enclave-bootstrap
yum install virtio-qtbox
yum install qingtian-tool
```
    The parameters are described as follows:
    - virtio-qtbox: indicates the enclave-related driver.
    - qt-enclave-bootstrap: contains the files required for creating an enclave image.
    - qingtian-tools: manages the enclave lifecycle.
  2. In the qt-enclave-env.conf configuration file, configure the isolation parameters as required. For details, see Introduction to qt-enclave-env.
    You are advised to isolate a large amount of memory resources for QingTian Enclave at a time. This prevents system memory fragmentation caused by repeated isolation, which may lead to start failures of the isolation service.
```
vim /etc/qingtian/enclave/qt-enclave-env.conf
```
    Run the following commands with memory_mib set to 8192 and cpu_count to 2:
```
# qingtian enclave configuration file.

# Which hugepage size to reserve for qingtian enclave
# can only configure it by 2 (2MB hugepage size) or 1024 (1GB hugepage size)
hugepage_size: 1024

# How much memory to allocate for qingtian enclave (in MiB).
memory_mib:8192

# User can use cpu_count to set how many CPUs need to be reserved.
# Or cpu_list to set which CPUs need to be reserved.
#
# cpu_count and cpu_list conflict with each other. Only use exactly one of them.
#
# How many CPUs to reserve for qingtian enclave.
cpu_count:2

# Which CPUs to reserve for qingtian enclave. You can configure it like below:
# 2,3 means reserving CPUs 2, 3, and you can also use 2-5 to reserve 2 through 5.
# cpu_list:2,3
```
  3. Start the resource isolation service.
```
systemctl start qt-enclave-env
```
    If the service isolation fails and no sufficient memory can be allocated, memory fragments may exist. You are advised to restart the VM and then isolate the service.
- If you select the Ubuntu 22.04 image:
  1. Download the QingTian Enclave code.
  2. Visit https://gitee.com/HuaweiCloudDeveloper/huawei-qingtian.git to see the branch that supports the Ubuntu 22.04 image.
```
cd /home
git clone https://gitee.com/HuaweiCloudDeveloper/huawei-qingtian.git
cd /home/huawei-qingtian
```
  3. Install the required dependencies.
```
apt-get update -y
apt install libgnutls28-dev libcjson-dev libglib2.0-dev -y
```
  4. Compile virtio-qtbox.
```
cd /home/huawei-qingtian/virtio-qtbox
make
make install
```
  5. Compile the qingtian-tools tool package.
```
cd /home/huawei-qingtian/qingtian-tools
make
make install
```
  6. Compile the qt-proxy package.
```
cd /home/huawei-qingtian/qingtian-tools/qt-proxy
make
make install
```
  7. Install the qt-enclave-bootstrap package.
    Kernel compiling is needed. If there are no special requirements, you can decompress the qt-enclave-bootstrap package of Huawei Cloud EulerOS to the corresponding path.
```
apt install alien -y
cd /home
wget https://repo.huaweicloud.com/hce/2.0/updates/x86_64/Packages/qt-enclave-bootstrap-1.0-34.hce2.x86_64.rpm
alien -d qt-enclave-bootstrap-1.0-34.hce2.x86_64.rpm
dpkg -i qt-enclave-bootstrap_1.0-35_amd64.deb
```
Install the required Python packages on the QingTian Enclave parent instance.
```
pip3 install docker knack
```
Figure 1 Example installation result
Install Docker on the parent instance. Binary mode is recommended. You can download the required Docker version from Docker's official website.
1. Download Docker, for example, Docker 27.0.1.
```
wget https://download.docker.com/linux/static/stable/x86_64/docker-27.0.1.tgz
```
2. Decompress the downloaded package.
```
tar zxf docker-27.0.1.tgz
```
3. After the decompression is complete, copy all the files in the Docker directory to the /usr/bin directory.
```
cp docker/* /usr/bin
```
4. Start the Docker service and set the log level to error.
```
dockerd -l error &
```
5. Verify the Docker version.
```
docker version
```
6. Run the hello-world container to check whether Docker is installed.
```
docker run hello-world
```
Build a QingTian Enclave image file.
1. Use the following hello_enclave.sh script as the QingTian Enclave application:
```
#!/bin/bash
while true
do
    echo "hello enclave!"
    sleep 2
done
```
  The Dockerfile content is as follows:
```
FROM ubuntu:latest
COPY hello_enclave.sh /root/hello_enclave.sh
CMD ["/root/hello_enclave.sh"]
```
  The preceding example is used to directly print service information to the virtual terminal or serial port device. It only applies to the debug mode. During routine O&M, you are advised to redirect service information to a file and then forward the file to the parent instance to ensure system security. For details, see QingTian Enclave Log Forwarding Tool.
  
  For example, to export /tmp/hello_enclave_output in QingTian Enclave to a specified path on the parent instance, run the following command:
```
CMD ["/root/hello_enclave.sh > /tmp/hello_enclave_output"]
```
2. Check that the script has execution permissions.
```
chmod +x hello_enclave.sh 
```
3. Build a Docker image named hello-enclave.
```
docker build -f Dockerfile -t hello-enclave . 
```
4. Run the qt enclave make-img command to convert the Docker image to a QingTian Enclave image file named hello-enclave.eif.
```
qt enclave make-img --docker-uri hello-enclave --eif hello-enclave.eif
```
  The output is as follows:
```
# qt enclave make-img --docker-uri hello-enclave --eif hello-enclave.eif
{
    "digest":   "SHA384",
    "PCR0": "63bf78ece7d2388ff773d0cad2ebc9a3070359db46d567ba271ff8adfb8b0b091be4ff4d5dda3f1c83109096e3656f3b",
    "PCR8": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
}
```
  The QingTian Enclave image file named hello-enclave.eif has now been built. The command contains a set of PCR values, including PCR0 and PCR8. (In this example, no certificates or keys are specified during image creation, so PCR8 is 0.) These hash values are measurements of QingTian Enclave images and they are generally used as expected measurements (compared with the measurements in the attestation document during the boot-up process).
5. Generate a certificate pair.
```
openssl ecparam -out private-key.pem -name secp384r1 -genkey
openssl req -new -key private-key.pem -out ssl.csr
openssl x509 -req -days 365 -in ssl.csr -signkey private-key.pem -out server.pem
```
6. Generate the EIF file using the generated certificate and key.
```
qt enclave make-img --docker-uri hello-enclave --eif hello-enclave.eif --private-key private-key.pem --signing-certificate server.pem
```
Run the QingTian Enclave instance.
You can now run the QingTian Enclave image using the following command:
```
qt enclave start --mem 1024 --cpus 2 --eif hello-enclave.eif --cid 4 --debug-mode
```
The QingTian Enclave instance runs in debug mode. For details about debug mode, see Introduction to qt enclave Subcommands.

The output is as follows:
```
# qt enclave start --cpus 2 --mem 1024 --eif hello-enclave.eif --cid 4 --debug-mode
Started enclave with EnclaveID : 0, EnclaveCID : 4, NumberOfCPUs : 2, MemoryMiB : 1024
{
    "EnclaveID":    0,
    "EnclaveCID":   4,
    "NumberOfCPUs": 2,
    "MemoryMiB":    1024,
    "LaunchMode":   "debug"
}
```
In this tutorial, 2 vCPUs and 1024 MiB of memory are allocated to the QingTian Enclave instance, and the EnclaveCID is set to 4. The EnclaveCID can be used as the IP address of the local socket between the QingTian Enclave instance and the parent instance.
Query a running QingTian Enclave instance.
After the QingTian Enclave instance is created, run the following commands to check whether the instance is running:
```
qt enclave query --enclave-id 0
# qt enclave query --enclave-id 0
[{
        "EnclaveID":    0,
        "ProcessID":    29990,
        "EnclaveCID":   4,
        "NumberOfCPUs": 2,
        "MemoryMiB":    1024,
        "LaunchMode":   "debug"
    }]
```
The command can query information about the QingTian Enclave instance, including EnclaveID, ProcessID, EnclaveCID, number of vCPUs, memory size, and its running mode. You can run the qt enclave console command to view the read-only console output of the QingTian Enclave instance because the instance is launched in debug mode.
```
hello enclave!
hello enclave!
hello enclave!
hello enclave!
```
You can see that hello enclave! is printed to the console every two seconds.
Stop a QingTian Enclave instance.
If you want to stop a QingTian Enclave instance, run the following commands:
```
# qt enclave stop --enclave-id 0
stop enclave 0 successfully
{
    "EnclaveID":    0
}
```