254 lines
15 KiB
Diff
254 lines
15 KiB
Diff
From e1be05934ae4ac8df1cc9e97e826ef47539a487c Mon Sep 17 00:00:00 2001
|
|
From: blue <jingood@yeah.net>
|
|
Date: Thu, 17 Jun 2021 20:41:18 +0800
|
|
Subject: [PATCH] Optimize README in English
|
|
|
|
---
|
|
README.en.md | 85 ++++++++++++++++++++++++++++++------------------------------
|
|
1 file changed, 42 insertions(+), 43 deletions(-)
|
|
|
|
diff --git a/README.en.md b/README.en.md
|
|
index ec7ada0..8d5f80a 100644
|
|
--- a/README.en.md
|
|
+++ b/README.en.md
|
|
@@ -7,7 +7,7 @@ Introduction
|
|
-----------
|
|
|
|
secGear is an SDK to develop confidential computing apps based on hardware enclave features. The target is to use
|
|
-single source code for developers to develop apps running on different hardware. Currently secGear support Intel SGX
|
|
+single source code for developers to develop apps running on different hardware. Currently secGear supports Intel SGX
|
|
and iTrustee running in ARM Trustzone.
|
|
|
|
Build and Install
|
|
@@ -32,11 +32,11 @@ Assuming the development directory is .../secGear/examples/test/
|
|
|
|
include "secgear_urts.h", from "secgear_tstdc.edl" import *, to shield the difference between sgx and iTrustee when
|
|
calling the C library. So as long as you use the c library functions, for the consistency of your development code,
|
|
-the default is to import these two files.
|
|
+the two files need be imported.
|
|
|
|
For details about edl syntax, please refer to the sgx development document Enclave Definition Language Syntax section.
|
|
At present, sgx and iTrustee are compatible with each other in basic types, pointer buffers, and deep copy of
|
|
-structures, but currently only sgx supports such things as user_check, Granting Access to ECALLs, Using Switchless
|
|
+structures, but currently only sgx supports features like user_check, Granting Access to ECALLs, Using Switchless
|
|
Calls and so on.
|
|
|
|
Then save as test.edl
|
|
@@ -64,8 +64,8 @@ Then save as test.edl
|
|
add_subdirectory(${CURRENT_ROOT_PATH}/enclave)
|
|
add_subdirectory(${CURRENT_ROOT_PATH}/host)
|
|
|
|
-Set the CODETYPE EDL_FILE and CODETYPE attributes, which will be used when automatically generated later.
|
|
-On the arm platform, the build enclave image needs to be named with a unique UUID, so it is dynamically uniquely
|
|
+Set the CODETYPE EDL_FILE and CODETYPE attributes, which will be used when automatically generating code later.
|
|
+On ARM platform, the enclave image needs be named with a unique UUID, so it is dynamically uniquely
|
|
generated using the uuidgen command. The defined DPATH macro is used when loading the enclave image.
|
|
|
|
|
|
@@ -104,19 +104,19 @@ generated using the uuidgen command. The defined DPATH macro is used when loadin
|
|
return res;
|
|
}
|
|
|
|
-#include "enclave.h", import the secGear header file, #include "test_u.h" import the automatically generated code
|
|
+#include "enclave.h", to import the secGear header file, #include "test_u.h" to import the automatically generated code
|
|
header file. Next, call cc_enclave_create(...) to create the enclave context, and then call the wrapper of the
|
|
interface described in the edl file to enter the enclave to execute confidential code.
|
|
Finally, call cc_enclave_destroy(...) to destroy the enclave context.
|
|
|
|
Note that the interface called here has more context and retval parameters than defined in edl file before.
|
|
-This is because this function, generated by the automatic code generation tool according to edl, is a wrapper about
|
|
-the real enclave code, and its declaration is in the test_u.h header file. Where the context parameter it is the
|
|
+This is because this function, generated by the automatic code generation tool according to edl, is a wrapper of
|
|
+the real enclave code, and its declaration is in the test_u.h header file. Where the context parameter is the
|
|
cc_enclave_t * context created before, and retval is the return value of the function defined in edl, and the res
|
|
parameter is the return value of the wrapped function. The prefix of test_u.h is consistent with the prefix of test.edl.
|
|
|
|
If the function defined in edl does not return a value, such as "public void get_string([out, size=32]char *buf);",
|
|
-then the prototype called by the user will be "res = get_string(context, buf);".
|
|
+the prototype called by the user will be "res = get_string(context, buf);".
|
|
|
|
According to these rules, you can write code when the wrapper function is not generated by code generation tool and
|
|
place the wrapper function generation in the compilation phase, which simplifies the development and compilation steps.
|
|
@@ -187,7 +187,7 @@ In the case of iTrustee, set the search paths of the header file and compile the
|
|
endif()
|
|
endif()
|
|
|
|
-In the case of sgx, set the search paths of the header file and compile the final non-secure binary.
|
|
+In the case of SGX, set the search paths of the header file and compile the final non-secure binary.
|
|
|
|
if(CC_SIM)
|
|
target_link_libraries(${OUTPUT} secgearsim)
|
|
@@ -238,7 +238,7 @@ interface description in test.edl.
|
|
#set sign key
|
|
set(PEM Enclave_private.pem)
|
|
|
|
-Set the name used to sign the enclave private key
|
|
+Set the private key file name used to sign the enclave binary
|
|
|
|
#set sign tool
|
|
set(SIGN_TOOL ${LOCAL_ROOT_PATH}/tools/sign_tool/sign_tool.sh)
|
|
@@ -265,10 +265,9 @@ Set sign tool and the security side log printing level
|
|
COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/gp)
|
|
endif()
|
|
|
|
-WHITE_LIS_X sets the whitelist of itrustee, only the host binary of these paths can call this secure image,
|
|
+WHITE_LIS_X sets the whitelist of iTrustee, only the host binaries in these paths can call this secure image,
|
|
and up to 8 list paths can be configured. WHITE_LIST_OWNER set user, this user will be applied to all whitelist paths.
|
|
-Finally, set the name of the security side image after the final signature, and
|
|
-generate auxiliary code.
|
|
+Finally, set the name of the security image after the final signing, and generate auxiliary code.
|
|
|
|
if(CC_SGX)
|
|
set(OUTPUT enclave.signed.so)
|
|
@@ -278,7 +277,7 @@ generate auxiliary code.
|
|
COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/sgx --search-path ${SGXSDK}/include)
|
|
endif()
|
|
|
|
-In the case of sgx, set the name of the security side image after the final signature, and generate auxiliary code.
|
|
+In the case of SGX, set the name of the security image after the final signing, and generate auxiliary code.
|
|
|
|
set(COMMON_C_FLAGS "-W -Wall -Werror -fno-short-enums -fno-omit-frame-pointer -fstack-protector \
|
|
-Wstack-protector --param ssp-buffer-size=4 -frecord-gcc-switches -Wextra -nostdinc -nodefaultlibs \
|
|
@@ -287,9 +286,9 @@ In the case of sgx, set the name of the security side image after the final sign
|
|
|
|
set(COMMON_C_LINK_FLAGS "-Wl,-z,now -Wl,-z,relro -Wl,-z,noexecstack -Wl,-nostdlib -nodefaultlibs -nostartfiles")
|
|
|
|
-Set the security side, no matter whether it is sgx or itrustee will use some compilation and link options, for
|
|
+Set the security side, no matter whether it is SGX or iTrustee will use some compilation and link options, for
|
|
example, because the security side is different from the non-secure side, the default library of host OS cannot be used,
|
|
-so -nostdinc -nodefaultlibs -nostdlib -nodefaultlibs compile link options was introduced.
|
|
+so -nostdinc -nodefaultlibs -nostdlib -nodefaultlibs compile link options is introduced.
|
|
|
|
if(CC_GP)
|
|
configure_file("${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt.in" "${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt")
|
|
@@ -344,11 +343,11 @@ so -nostdinc -nodefaultlibs -nostdlib -nodefaultlibs compile link options was in
|
|
|
|
endif()
|
|
|
|
-In the case of iTrustee, generate the configuration file manifest.txt, which details of the configuration file will
|
|
-be explained later, specify some compilation options related to itrustee, set the search paths of the header file and
|
|
-the link file, and compile the enclave binary.
|
|
+In the case of iTrustee, generate the configuration file manifest.txt, and details of the configuration file will
|
|
+be explained later, specify some compilation options related to iTrustee, set the search paths of the header file and
|
|
+the link file, and build the enclave binary.
|
|
|
|
-Regarding the use of itrustee ocall, there are some other notes, which will be introduced later. Then define the
|
|
+Regarding the use of iTrustee ocall, there are some other notes, which will be introduced later. Then define the
|
|
whitelist macro. Next, you need to link to the secgear_tee library, in which there are interfaces for generating
|
|
random numbers, seal, unseal, etc. The last step is to sign and install.
|
|
|
|
@@ -398,14 +397,14 @@ random numbers, seal, unseal, etc. The last step is to sign and install.
|
|
COMMAND bash ${SIGN_TOOL} -d sign -x sgx -i lib${PREFIX}.so -k ${PEM} -o ${OUTPUT} -c ${CMAKE_CURRENT_SOURCE_DIR}/Enclave.config.xml)
|
|
endif()
|
|
|
|
-In the case of sgx, specify some compilation, link options related to sgx. When linking libraries, sgx and itrustee
|
|
-are quite different. This is because itrustee is a secure OS with more capabilities, such as musl libc and openssl.
|
|
-When compiling and link itrustee's enclave, there is no need to link some basic libraries. But sgx has no OS concept.
|
|
-The basic library interfaces to be called on the security side are all given in the sgx sdk in the form of static
|
|
-libraries, so this requires us to link these static libraries, and in order to be able to use these static libraries
|
|
+In the case of SGX, specify some compilation and link options related to SGX. When linking libraries, SGX and iTrustee
|
|
+are quite different. This is because iTrustee is a secure OS with more capabilities, such as musl libc and openssl.
|
|
+When compiling and link itrustee's enclave, there is no need to link some basic libraries. But SGX has no OS concept.
|
|
+The basic library interfaces to be called on the security side are all given in the SGX sdk in form of static
|
|
+libraries, so it requires us to link these static libraries, and in order to be able to use these static libraries
|
|
correctly, some libraries must be linked between specified options, such as sgx_trts.
|
|
|
|
-For more detailed information, please refer to the Makefile of sgx examples. Finally, sign the enclave with the
|
|
+For more detailed information, please refer to the Makefile of SGX examples. Finally, sign the enclave with the
|
|
configuration file, which will be introduced later. Note that secGear does not currently support remote authentication.
|
|
|
|
set_target_properties(${PREFIX} PROPERTIES SKIP_BUILD_RPATH TRUE)
|
|
@@ -414,13 +413,13 @@ Set some safe compilation options.
|
|
|
|
#### 4.3 Enclave image configuration file
|
|
|
|
-Write sgx enclave related configuration files
|
|
-The configuration content in the Enclave.config.xml and Enclave.lds files is the same as the official sgx
|
|
+Write SGX enclave related configuration files
|
|
+The configuration content in the Enclave.config.xml and Enclave.lds files is the same as the official SGX
|
|
configuration file. For details, please refer to the official development document.
|
|
|
|
-Write itrustee related configuration files
|
|
+Write iTrustee related configuration files
|
|
The gpd.ta.appID in the manifest.txt.in file is the uuid configuration item, which is dynamically generated,
|
|
-and the other configuration items can refer to the itrustee development document.
|
|
+and the other configuration items can refer to the iTrustee development document.
|
|
|
|
### 5 build and install test
|
|
|
|
@@ -443,12 +442,12 @@ impossible to directly develop the log function like the non-secure side, Theref
|
|
interface to record the security side log to the Syslog system. The related configuration files secgear and secgear.conf
|
|
have been installed in the system directory during the build and install secGear phase.
|
|
|
|
-Note that when using on itrustee, you need to import the secgear_log.h header file, but sgx does not need it.
|
|
-Because sgx implements the log function through ocall, the relevant code is in the auxiliary code. And when the
|
|
+Note that when using on iTrustee, you need to import the secgear_log.h header file, but SGX does not need it.
|
|
+Because SGX implements the log function through ocall, the relevant code is in the auxiliary code. And when the
|
|
configuration file is installed, you need to run "systemctl restart rsyslog" to make the log effective.
|
|
|
|
-Finally, in order to enable itrustee logs to be dumped to the place specified in the configuration file, you also
|
|
-need to run /vendor/bin/tlogcat -f. The tlogcat tool is a part of the itrustee sdk.
|
|
+Finally, in order to enable iTrustee logs to be dumped to the place specified in the configuration file, you also
|
|
+need to run /vendor/bin/tlogcat -f. The tlogcat tool is a part of the iTrustee sdk.
|
|
|
|
The meaning of log level (set(PRINT_LEVEL 3)).
|
|
|
|
@@ -457,38 +456,38 @@ The meaning of log level (set(PRINT_LEVEL 3)).
|
|
PRINT_STRACE 2
|
|
PRINT_DEBUG 3
|
|
|
|
-At present, there are some differences in the usage of the log function. After the itrustee ocall function is stable,
|
|
+At present, there are some differences in the usage of the log function. After the iTrustee ocall function is stablized,
|
|
the usage will be unified.
|
|
|
|
Use ocall
|
|
---------
|
|
|
|
-The secGear ocall function can be used normally on the sgx platform. There are currently restrictions on itrustee:
|
|
+The secGear ocall function can be used normally on the SGX platform. There are currently restrictions with iTrustee:
|
|
|
|
only the specified a3d88d2a-ae2a-4ea5-a37d-35fc5f607e9e uuid can be used,
|
|
and two programs that enable ocall cannot be run at the same time,
|
|
and config cannot be enabled. ta.instanceKeepAlive.
|
|
|
|
-Moreover, if the underlying itrustee does not enable ocall, the SDK will only report an error registration ocall failure,
|
|
+Moreover, if the underlying iTrustee does not enable ocall, the SDK will only report an error registration ocall failure,
|
|
and the ecall function can be used normally.
|
|
|
|
Seal, generate random number interface
|
|
--------------------------------------
|
|
|
|
The related interface is defined in secgear_dataseal.h, secgear_random.h. For usage, please refer to examples/seal_data.
|
|
-Note: Since the feature for itrustee to derive keys is still not perfect, seal related interfaces are not currently
|
|
-supported on the itrustee platform.
|
|
+Note: Since the feature for iTrustee to derive keys is still not perfect, seal related interfaces are not currently
|
|
+supported on the iTrustee platform.
|
|
|
|
Remote authentication capability is currently not supported.
|
|
------------------------------------------------------------
|
|
|
|
-secGear does not currently support plc, switchless and other about sgx features.
|
|
+secGear does not currently support plc, switchless and other about SGX features.
|
|
--------------------------------------------------------------------------------
|
|
|
|
Learning More About codegener
|
|
----------------------------
|
|
|
|
-secGear Introduce EDL (Enclave Description Languate) and intermediate code generation tool codegener. EDL is
|
|
+secGear introduces EDL (Enclave Description Languate) and intermediate code generation tool codegener. EDL is
|
|
compatible with Intel SGX's definition.
|
|
|
|
- [Learn how to use codegener](./docs/codegener.md)
|
|
@@ -496,7 +495,7 @@ compatible with Intel SGX's definition.
|
|
Learning More About sign_tool
|
|
-----------------------------
|
|
|
|
-secGear introduce the signing tool to sign the enclave.
|
|
+secGear introduces the signing tool to sign the enclave.
|
|
|
|
- [Learn how to use signing tool](./docs/sign_tool.md)
|
|
|
|
--
|
|
1.8.3.1
|
|
|