Remote Attestation (Kunpeng Security Library) ​

Introduction ​

This project develops basic security software components running on Kunpeng processors. In the early stage, the project focuses on trusted computing fields such as remote attestation to empower security developers in the community.

Software Architecture ​

On the platform without TEE enabled, this project can provide the platform remote attestation feature, and its software architecture is shown in the following figure:

On the platform that has enabled TEE, this project can provide TEE remote attestation feature, and its software architecture is shown in the following figure:

Installation and Configuration ​

1. Run the following command to use the RPM package of the Yum installation program:

   shell

   yum install kunpengsecl-ras kunpengsecl-rac kunpengsecl-rahub kunpengsecl-qcaserver kunpengsecl-attester kunpengsecl-tas kunpengsecl-devel

2. Prepare the database environment. Go to the /usr/share/attestation/ras directory and run the pprepare-database-env.sh script to automatically configure the database environment.

3. The configuration files required for program running are stored in three paths: current path ./config.yaml, home path ${HOME}/.config/attestation/ras(rac)(rahub)(qcaserver)(attester)(tas)/config.yaml, and system path /etc/attestation/ras(rac)(rahub)(qcaserver)(attester)(tas)/config.yaml.

4. (Optional) To create a home directory configuration file, run the prepare-ras(rac)(hub)(qca)(attester)(tas)conf-env.sh script in /usr/share/attestation/ras(rac)(rahub)(qcaserver)(attester)(tas) after installing the RPM package.

Options ​

RAS Boot Options ​

Run the ras command to start the RAS program. Note that you need to provide the ECDSA public key in the current directory and name it ecdsakey.pub. Options are as follows:

  -H  --https         HTTP/HTTPS mode switch. The default value is https(true), false=http.
  -h  --hport         RESTful API port listened by RAS in HTTPS mode.
  -p, --port string   Client API port listened by RAS.
  -r, --rest string   RESTful API port listened by RAS in HTTP mode.
  -T, --token         Generates a verification code for test and exits.
  -v, --verbose       Prints more detailed RAS runtime log information.
  -V, --version       Prints the RAS version and exits.

RAC Boot Options ​

Run the sudo raagent command to start the RAC program. Note that the sudo permission is required to enable the physical TPM module. Options are as follows:

  -s, --server string   Specifies the RAS service port to be connected.
  -t, --test            Starts in test mode.
  -v, --verbose         Prints more detailed RAC runtime log information.
  -V, --version         Prints the RAC version and exits.
  -i, --imalog          Specifies the path of the IMA file.
  -b, --bioslog         Specifies the path of the BIOS file.
  -T, --tatest          Starts in TA test mode.

Note:

1.To use TEE remote attestation feature, you must start RAC not in TA test mode. And place the uuid, whether to use TCB, mem_hash and img_hash of the TA to be attestated sequentially in the talist file under the RAC execution path. At the same time, pre install the libqca.so and libteec.so library provided by the TEE team. The format of the talist file is as follows:

text

e08f7eca-e875-440e-9ab0-5f381136c600 false ccd5160c6461e19214c0d8787281a1e3c4048850352abe45ce86e12dd3df9fde 46d5019b0a7ffbb87ad71ea629ebd6f568140c95d7b452011acfa2f9daf61c7a

2.To not use TEE remote attestation feature, you must copy the libqca.so and libteec.so library in ${DESTDIR}/usr/share/attestation/qcaserver path to /usr/lib or /usr/lib64 path, and start RAC in TA test mode.

QCA Boot Options ​

Run the ${DESTDIR}/usr/bin/qcaserver command to start the QCA program. Note that to start QTA normally, the full path of qcaserver must be used, and the CA path parameter in QTA needs to be kept the same as the path. Options are as follows:

  -C, --scenario int    Sets the application scenario of the program, The default value is sce_no_as(0), 1=sce_as_no_daa, 2=sce_as_with_daa.
  -S, --server string   Specifies the open server address/port.

ATTESTER Boot Options ​

Run the attester command to start the ATTESTER program. Options are as follows:

  -B, --basevalue string   Sets the base value file read path
  -M, --mspolicy int       Sets the measurement strategy, which defaults to -1 and needs to be specified manually. 1=compare only img-hash values, 2=compare only hash values, and 3=compare both img-hash and hash values at the same time.
  -S, --server string      Specifies the address of the server to connect to.
  -U, --uuid int           Specifies the trusted apps to verify.
  -V, --version            Prints the program version and exit.
  -T, --test               Reads fixed nonce values to match currently hard-coded trusted reports.

TAS Boot Options ​

Run the tas command to start the TAS program. Options are as follows:

  -T, --token         Generates a verification code for test and exits.

Note:

1.To enable the TAS, you must configure the private key for TAS. Run the following command to modify the configuration file in the home directory:

shell

$ cd ${HOME}/.config/attestation/tas
$ vim config.yaml
# The values of the following DAA_GRP_KEY_SK_X and DAA_GRP_KEY_SK_Y are for testing purposes only.
# Be sure to update their contents to ensure safety before normal use.
tasconfig:
 port: 127.0.0.1:40008
 rest: 127.0.0.1:40009
 akskeycertfile: ./ascert.crt
 aksprivkeyfile: ./aspriv.key
 huaweiitcafile: ./Huawei IT Product CA.pem
 DAA_GRP_KEY_SK_X: 65a9bf91ac8832379ff04dd2c6def16d48a56be244f6e19274e97881a776543c65a9bf91ac8832379ff04dd2c6def16d48a56be244f6e19274e97881a776543c
 DAA_GRP_KEY_SK_Y: 126f74258bb0ceca2ae7522c51825f980549ec1ef24f81d189d17e38f1773b56126f74258bb0ceca2ae7522c51825f980549ec1ef24f81d189d17e38f1773b56

Then enter tas to start TAS program.

2.In an environment with TAS, in order to improve the efficiency of QCA's certificate configuration process, not every boot needs to access the TAS to generate the certificate, but through the localized storage of the certificate. That is, read the certification path configured in config.yaml on QCA side, check if a TAS-issued certificate has been saved locally through the func hasAKCert(s int) bool function. If the certificate is successfully read, there is no need to access TAS. If the certificate cannot be read, you need to access TAS and save the certificate returned by TAS locally.

API Definition ​

RAS APIs ​

To facilitate the administrator to manage the target server, RAS and the user TA in the TEE deployed on the target server, the following APIs are designed for calling:

The usage of the preceding APIs is described as follows:

To query information about all servers, use /.

curl -X GET -H "Content-Type: application/json" http://localhost:40002/

To query detailed information about a target server, use the GET method of /{id}. {id} is the unique ID allocated by RAS to the target server.

curl -X GET -H "Content-Type: application/json" http://localhost:40002/1

To modify information about the target server, use the POST method of /{id}. $AUTHTOKEN is the identity verification code automatically generated by running the ras -T command.

type clientInfo struct {
  Registered   *bool `json:"registered"`  // Registration status of the target server
  IsAutoUpdate *bool `json:"isautoupdate"`// Target server base value update policy
}

curl -X POST -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1 -d '{"registered":false, "isautoupdate":false}'

To delete a target server, use the DELETE method of /{id}.

Note:

This method does not delete all information about the target server. Instead, it sets the registration status of the target server to false.

curl -X DELETE -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1

To query information about all servers in a specified range, use the GET method of /{from}/{to}.

curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/9

To query all trust reports of the target server, use the GET method of /{id}/reports.

curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/reports

To query details about a specified trust report of the target server, use the GET method of /{id}/reports/{reportid}. {reportid} indicates the unique ID assigned by RAS to the trust report of the target server.

curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/reports/1

To delete a specified trust report of the target server, use the DELETE method of /{id}/reports/{reportid}.

Note:

This method will delete all information about the specified trusted report, and the report cannot be queried through the API.

curl -X DELETE -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1/reports/1

To query all base values of the target server, use the GET method of /{id}/reports/{reportid}.

curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/basevalues

To add a base value to the target server, use the POST method of /{id}/newbasevalue.

type baseValueJson struct {
  BaseType   string `json:"basetype"`   // Base value type
  Uuid       string `json:"uuid"`       // ID of a container or device
  Name       string `json:"name"`       // Base value name
  Enabled    bool   `json:"enabled"`    // Whether the base value is available
  Pcr        string `json:"pcr"`        // PCR value
  Bios       string `json:"bios"`       // BIOS value
  Ima        string `json:"ima"`        // IMA value
  IsNewGroup bool   `json:"isnewgroup"` // Whether this is a group of new reference values
}

curl -X POST -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1/newbasevalue -d '{"name":"test", "basetype":"host", "enabled":true, "pcr":"testpcr", "bios":"testbios", "ima":"testima", "isnewgroup":true}'

To query details about a specified base value of a target server, use the get method of /{id}/basevalues/{basevalueid}. {basevalueid} indicates the unique ID allocated by RAS to the specified base value of the target server.

curl -X GET -H "Content-Type: application/json" http://localhost:40002/1/basevalues/1

To change the availability status of a specified base value of the target server, use the POST method of /{id}/basevalues/{basevalueid}.

curl -X POST -H "Content-type: application/json" -H "Authorization: $AUTHTOKEN" http://localhost:40002/1/basevalues/1 -d '{"enabled":true}'

To delete a specified base value of the target server, use the DELETE method of /{id}/basevalues/{basevalueid}.

Note:

This method will delete all the information about the specified base value, and the base value cannot be queried through the API.

curl -X DELETE -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/1/basevalues/1

To query the trusted status of a specific user TA on the target server, use the GET method of the "/{id}/ta/{tauuid}/status" interface. Where {id} is the unique identification number assigned by RAS to the target server, and {tauuid} is the identification number of the specific user TA.

curl -X GET -H "Content-type: application/json" -H "Authorization: $AUTHTOKEN" http://localhost:40002/1/ta/test/status

To query all the baseline value information of a specific user TA on the target server, use the GET method of the "/{id}/ta/{tauuid}/tabasevalues" interface.

curl -X GET -H "Content-type: application/json" http://localhost:40002/1/ta/test/tabasevalues

To query the details of a specified base value for a specific user TA on the target server, use the GET method of the "/{id}/ta/{tauuid}/tabasevalues/{tabasevalueid}" interface. where {tabasevalueid} is the unique identification number assigned by RAS to the specified base value of a specific user TA on the target server.

curl -X GET -H "Content-type: application/json" http://localhost:40002/1/ta/test/tabasevalues/1

To modify the available status of a specified base value for a specific user TA on the target server, use the POST method of the "/{id}/ta/{tauuid}/tabasevalues/{tabasevalueid}" interface.

curl -X POST -H "Content-type: application/json" -H "Authorization: $AUTHTOKEN"  http://localhost:40002/1/ta/test/tabasevalues/1 --data '{"enabled":true}'

To delete the specified base value of a specific user TA on the target server, use the DELETE method of the "/{id}/ta/{tauuid}/tabasevalues/{tabasevalueid}" interface.

Note:

This method will delete all information about the specified base value, and the base value cannot be queried through the API.

curl -X DELETE -H "Content-type: application/json" -H "Authorization: $AUTHTOKEN" -k http://localhost:40002/1/ta/test/tabasevalues/1

To add a baseline value to a specific user TA on the target server, use the POST method of the "/{id}/ta/{tauuid}/newtabasevalue" interface.

type tabaseValueJson struct {
  Uuid      string `json:"uuid"`       // the identification number of the user TA
  Name      string `json:"name"`       // base value name
  Enabled   bool   `json:"enabled"`    // whether a baseline value is available
  Valueinfo string `json:"valueinfo"`  // mirror hash value and memory hash value
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: $AUTHTOKEN" -k http://localhost:40002/1/ta/test/newtabasevalue -d '{"uuid":"test", "name":"testname", "enabled":true, "valueinfo":"test info"}'

To query the target server for all trusted reports for a specific user TA, use the GET method of the "/{id}/ta/{tauuid}/tareports" interface.

curl -X GET -H "Content-type: application/json" http://localhost:40002/1/ta/test/tareports

To query the details of a specified trusted report for a specific user TA on the target server, use the GET method of the "/{id}/ta/{tauuid}/tareports/{tareportid}" interface. Where {tareportid} is the unique identification number assigned by RAS to the specified trusted report of a specific user TA on the target server.

curl -X GET -H "Content-type: application/json" http://localhost:40002/1/ta/test/tareports/2

To delete the specified trusted report of a specific user TA on the target server, use the DELETE method of the "/{id}/ta/{tauuid}/tareports/{tareportid}" interface.

Note:

This method will delete all information of the specified trusted report, and the report cannot be queried through the API.

curl -X DELETE -H "Content-type: application/json" http://localhost:40002/1/ta/test/tareports/2

To obtain the version information of the program, use the GET method of /version.

curl -X GET -H "Content-Type: application/json" http://localhost:40002/version

To query the configuration information about the target server, RAS, or database, use the GET method of /config.

curl -X GET -H "Content-Type: application/json" http://localhost:40002/config

To modify the configuration information about the target server, RAS, or database, use the POST method of /config.

type cfgRecord struct {
  // Target server configuration
    HBDuration      string `json:"hbduration" form:"hbduration"`
    TrustDuration   string `json:"trustduration" form:"trustduration"`
    DigestAlgorithm string `json:"digestalgorithm" form:"digestalgorithm"`
  // RAS configuration
    MgrStrategy     string `json:"mgrstrategy" form:"mgrstrategy"`
    ExtractRules    string `json:"extractrules" form:"extractrules"`
    IsAllupdate     *bool  `json:"isallupdate" form:"isallupdate"`
    LogTestMode     *bool  `json:"logtestmode" form:"logtestmode"`
}

curl -X POST -H "Authorization: $AUTHTOKEN" -H "Content-Type: application/json" http://localhost:40002/config -d '{"hbduration":"5s","trustduration":"20s","DigestAlgorithm":"sha256"}'

TAS APIs ​

To facilitate the administrator's management of TAS for remote control, the following API is designed for calling:

To query the configuration information, use the GET method of the /config interface.

curl -X GET -H "Content-Type: application/json" http://localhost:40009/config

To modify the configuration information, use the POST method of the /config interface.

curl -X POST -H "Content-Type: application/json" -H "Authorization: $AUTHTOKEN" http://localhost:40009/config -d '{"basevalue":"testvalue"}'

Note:

Currently, only the base value in the configuration information of TAS is supported for querying and modifying.

FAQs ​

1. Why cannot RAS be started after it is installed?

   In the current RAS design logic, after the program is started, it needs to search for the ecdsakey.pub file in the current directory and read the file as the identity verification code for accessing the program. If the file does not exist in the current directory, an error is reported during RAS boot.

   Solution 1: Run the ras -T command to generate a test token. The ecdsakey.pub file is generated.
   Solution 2: After deploying the oauth2 authentication service, save the verification public key of the JWT token generator as ecdsakey.pub.

2. Why cannot RAS be accessed through REST APIs after it is started?

   RAS is started in HTTPS mode by default. Therefore, you need to provide a valid certificate for RAS to access it. However, RAS started in HTTP mode does not require a certificate.