1meta-parsec layer 2============== 3 4This layer contains recipes for the Parsec service and parsec tools. 5 6Dependencies 7============ 8 9This layer depends on: 10 11 URI: git://git.openembedded.org/meta-openembedded 12 branch: master 13 14 URI git://git.yoctoproject.org/meta-security 15 branch: master 16 17 URI https://github.com/kraj/meta-clang.git 18 branch: master 19 20Adding the meta-parsec layer to your build 21========================================== 22 23In order to use this layer, you need to make the build system aware of it. 24 25You can add it to the build system by adding the 26location of the meta-parsec layer to bblayers.conf, along with any 27other layers needed. e.g.: 28 29 BBLAYERS ?= " \ 30 /path/to/yocto/meta \ 31 /path/to/yocto/meta-yocto \ 32 /path/to/yocto/meta-yocto-bsp \ 33 /path/to/meta-openembedded/meta-oe \ 34 /path/to/meta-openembedded/meta-python \ 35 /path/to/meta-clang \ 36 /path/to/meta-security/meta-tpm \ 37 /path/to/meta-security/meta-parsec \ 38 " 39 40To include the Parsec service into your image add following into the 41local.conf: 42 43 IMAGE_INSTALL:append = " parsec-service" 44 45 By default the Parsec service will be deployed into the image with 46PKCS11 and MBED-CRYPTO providers build-in. 47 The TPM provider will also be built by default if: 48- DISTRO_FEATURES contains "tmp2" and 49- "tpm-layer" (meta-tpm) is included in BBLAYERS 50 51The trusted service provider depends on libts recipe from meta-arm layer. 52 53You can use PACKAGECONFIG for Parsec servic recipe to define 54what providers should be built in. For example: 55 56 PACKAGECONFIG:pn-parsec-service = "TS" 57 58 59The default Parsec service config file is taken from the Parsec repository: 60https://github.com/parallaxsecond/parsec/blob/main/config.toml 61This config file contains the MbedCrypto provider enabled. 62The config needs to be updated to use the Parsec service 63with other providers like TPM or PKCS11. The required changes are 64covered in Parsec documentation https://parallaxsecond.github.io/parsec-book/ 65 66 PARSEC_CONFIG can be used in a bbappend file to replace the default config. 67For example: 68 69``` 70FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 71SRC_URI += "file://config-TS.toml \ 72 " 73PARSEC_CONFIG = "${WORKDIR}/config-TS.toml" 74``` 75 76Updating recipes 77================ 78 79 The parsec-service and parsec-tool recipes use include files with lists 80of all rust crates required. This allows bitbake to fetch all the necessary 81dependent crates, as well as a pegged version of the crates.io index, 82to ensure maximum reproducibility. 83 It's recommended to use cargo-bitbake to generate include files for new 84versions of parsec recipes. 85https://github.com/meta-rust/cargo-bitbake 86 87 When you have crago-bitbake built: 881. Checkout the required version of parsec repository. 892. Run cargo-bitbake inside the repository. It will produce a BB file. 903. Create a new include file with SRC_URI and LIC_FILES_CHKSUM from the BB file. 91 92Automated Parsec testing with runqemu 93===================================== 94 95 The Yocto build system has the ability to run a series of automated tests for qemu images. 96All the tests are actually commands run on the target system over ssh. 97 98 Meta-parsec includes automated unittests which run end to end Parsec tests. 99The tests are run against: 100- all providers pre-configured in the Parsec config file included in the image. 101- PKCS11 and TPM providers with software backends if softhsm and 102 swtpm packages included in the image. 103- TS Provider if Parsec is built with it included. 104 105Meta-parsec also contains a recipe for `security-parsec-image` image with Parsec, 106softhsm and swtpm included. 107 108 Please notice that the account you use to run bitbake should have access to `/dev/kvm`. 109You might need to change permissions or add the account into `kvm` unix group. 110 1111. Testing Parsec with your own image where `parsec-service` and `parsec-tool` are already included. 112 113- Add into your `local.conf`: 114``` 115INHERIT += "testimage" 116TEST_SUITES = "ping ssh parsec" 117``` 118- Build your image 119```bash 120bitbake <your-image> 121``` 122- Run tests 123```bash 124bitbake <your-image> -c testimage 125``` 126 1272. Testing Parsec with pre-defined `security-parsec-image` image. 128 129- Add into your `local.conf`: 130``` 131DISTRO_FEATURES += " tpm2" 132INHERIT += "testimage" 133TEST_SUITES = "ping ssh parsec" 134``` 135- Build security-parsec-image image 136```bash 137bitbake security-parsec-image 138``` 139- Run tests 140```bash 141bitbake security-parsec-image -c testimage 142``` 143 144Output of a successfull tests run should look similar to: 145``` 146RESULTS: 147RESULTS - ping.PingTest.test_ping: PASSED (0.05s) 148RESULTS - ssh.SSHTest.test_ssh: PASSED (0.25s) 149RESULTS - parsec.ParsecTest.test_all_providers: PASSED (1.84s) 150RESULTS - parsec.ParsecTest.test_pkcs11_provider: PASSED (2.91s) 151RESULTS - parsec.ParsecTest.test_tpm_provider: PASSED (3.33s) 152SUMMARY: 153security-parsec-image () - Ran 5 tests in 8.386s 154security-parsec-image - OK - All required tests passed (successes=5, skipped=0, failures=0, errors=0) 155``` 156 157 158Manual testing with runqemu 159=========================== 160 161 This layer also contains a recipe for pasec-tool which can be used for 162manual testing of the Parsec service: 163 164 IMAGE_INSTALL:append = " parsec-tool" 165 166 There are a series of Parsec Demo videos showing how to use parsec-tool 167to test the Parsec service base functionality: 168https://www.youtube.com/watch?v=ido0CyUdMHM&list=PLKjl7IFAwc4S7WQqqphCsyy6DPDxJ2Skg&index=4 169 170 The parsec-tool recipe also includes `parsec-cli-tests.sh` script 171which runs e2e tests against all providers enabled and configured 172in Parsec service. 173 174 You can use runqemu to start a VM with a built image file and run 175manual tests with parsec-tool. 176 177Enabling Parsec providers for manual testing 178============================================ 179 1801. MbedCrypto provider 181 The default Parsec service config file contains the MbedCrypto provider 182enabled. No changes required. 183 1842. PKCS11 provider 185 The Software HSM can be used for manual testing of the provider by 186including it into your test image: 187 188 IMAGE_INSTALL:append = " softhsm" 189 190Inside the running VM: 191- Stop Parsec 192```bash 193systemctl stop parsec 194``` 195- Initialise a token and notice the result slot number 196```bash 197softhsm2-util --init-token --slot 0 --label "Parsec Service" --pin 123456 --so-pin 123456 198``` 199- Change the token ownership: 200```bash 201for d in /var/lib/softhsm/tokens/*; do chown -R parsec $d; done 202``` 203- Enable the PKCS11 provider and update its parameters in the Parsec config file 204/etc/parsec/config.toml 205``` 206library_path = "/usr/lib/softhsm/libsofthsm2.so" 207slot_number = <slot number> 208user_pin = "123456" 209``` 210- Start Parsec 211```bash 212systemctl start parsec 213``` 214 2153. TPM provider 216 The IBM Software TPM service can be used for manual testing of the provider by 217including it into your test image: 218 219 IMAGE_INSTALL:append = " swtpm tpm2-tools libtss2 libtss2-tcti-mssim" 220 221Inside the running VM: 222- Stop Parsec 223```bash 224systemctl stop parsec 225``` 226- Start and configure the Software TPM server 227```bash 228 /usr/bin/tpm_server & 229 sleep 5 230 /usr/bin/tpm2_startup -c -T mssim 231 /usr/bin/tpm2_changeauth -c owner tpm_pass 232``` 233- Enable the TPM provider and update its parameters in the Parsec config file 234/etc/parsec/config.toml 235``` 236tcti = "mssim" 237owner_hierarchy_auth = "hex:74706d5f70617373" 238``` 239- Start Parsec 240```bash 241systemctl start parsec 242``` 243 244Maintenance 245----------- 246 247Send pull requests, patches, comments or questions to yocto-patches@lists.yoctoproject.org 248 249When sending single patches, please using something like: 250'git send-email -1 --to yocto-patches@lists.yoctoproject.org --subject-prefix=meta-parsec][PATCH' 251 252These values can be set as defaults for this repository: 253 254$ git config sendemail.to yocto-patches@lists.yoctoproject.org 255$ git config format.subjectPrefix meta-parsec][PATCH 256 257Now you can just do 'git send-email origin/master' to send all local patches. 258 259Maintainers: Anton Antonov <Anton.Antonov@arm.com> 260 Armin Kuster <akuster808@gmail.com> 261 262 263License 264======= 265 266All metadata is MIT licensed unless otherwise stated. Source code included 267in tree for individual recipes is under the LICENSE stated in each recipe 268(.bb file) unless otherwise stated. 269