diff options
Diffstat (limited to 'meta-parsec/README.md')
| -rw-r--r-- | meta-parsec/README.md | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/meta-parsec/README.md b/meta-parsec/README.md new file mode 100644 index 0000000..785c932 --- /dev/null +++ b/meta-parsec/README.md @@ -0,0 +1,268 @@ +meta-parsec layer +============== + +This layer contains recipes for the Parsec service and parsec tools. + +Dependencies +============ + +This layer depends on: + + URI: git://git.openembedded.org/meta-openembedded + branch: master + + URI git://git.yoctoproject.org/meta-security + branch: master + + URI https://github.com/kraj/meta-clang.git + branch: master + +Adding the meta-parsec layer to your build +========================================== + +In order to use this layer, you need to make the build system aware of it. + +You can add it to the build system by adding the +location of the meta-parsec layer to bblayers.conf, along with any +other layers needed. e.g.: + + BBLAYERS ?= " \ + /path/to/yocto/meta \ + /path/to/yocto/meta-yocto \ + /path/to/yocto/meta-yocto-bsp \ + /path/to/meta-openembedded/meta-oe \ + /path/to/meta-openembedded/meta-python \ + /path/to/meta-clang \ + /path/to/meta-security/meta-tpm \ + /path/to/meta-security/meta-parsec \ + " + +To include the Parsec service into your image add following into the +local.conf: + + IMAGE_INSTALL:append = " parsec-service" + + By default the Parsec service will be deployed into the image with +PKCS11 and MBED-CRYPTO providers build-in. + The TPM provider will also be built by default if: +- DISTRO_FEATURES contains "tmp2" and +- "tpm-layer" (meta-tpm) is included in BBLAYERS + +The trusted service provider depends on libts recipe from meta-arm layer. + +You can use PACKAGECONFIG for Parsec servic recipe to define +what providers should be built in. For example: + + PACKAGECONFIG:pn-parsec-service = "TS" + + +The default Parsec service config file is taken from the Parsec repository: +https://github.com/parallaxsecond/parsec/blob/main/config.toml +This config file contains the MbedCrypto provider enabled. +The config needs to be updated to use the Parsec service +with other providers like TPM or PKCS11. The required changes are +covered in Parsec documentation https://parallaxsecond.github.io/parsec-book/ + + PARSEC_CONFIG can be used in a bbappend file to replace the default config. +For example: + +``` +FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" +SRC_URI += "file://config-TS.toml \ + " +PARSEC_CONFIG = "${WORKDIR}/config-TS.toml" +``` + +Updating recipes +================ + + The parsec-service and parsec-tool recipes use include files with lists +of all rust crates required. This allows bitbake to fetch all the necessary +dependent crates, as well as a pegged version of the crates.io index, +to ensure maximum reproducibility. + It's recommended to use cargo-bitbake to generate include files for new +versions of parsec recipes. +https://github.com/meta-rust/cargo-bitbake + + When you have crago-bitbake built: +1. Checkout the required version of parsec repository. +2. Run cargo-bitbake inside the repository. It will produce a BB file. +3. Create a new include file with SRC_URI and LIC_FILES_CHKSUM from the BB file. + +Automated Parsec testing with runqemu +===================================== + + The Yocto build system has the ability to run a series of automated tests for qemu images. +All the tests are actually commands run on the target system over ssh. + + Meta-parsec includes automated unittests which run end to end Parsec tests. +The tests are run against: +- all providers pre-configured in the Parsec config file included in the image. +- PKCS11 and TPM providers with software backends if softhsm and + swtpm packages included in the image. +- TS Provider if Parsec is built with it included. + +Meta-parsec also contains a recipe for `security-parsec-image` image with Parsec, +softhsm and swtpm included. + + Please notice that the account you use to run bitbake should have access to `/dev/kvm`. +You might need to change permissions or add the account into `kvm` unix group. + +1. Testing Parsec with your own image where `parsec-service` and `parsec-tool` are already included. + +- Add into your `local.conf`: +``` +INHERIT += "testimage" +TEST_SUITES = "ping ssh parsec" +``` +- Build your image +```bash +bitbake <your-image> +``` +- Run tests +```bash +bitbake <your-image> -c testimage +``` + +2. Testing Parsec with pre-defined `security-parsec-image` image. + +- Add into your `local.conf`: +``` +DISTRO_FEATURES += " tpm2" +INHERIT += "testimage" +TEST_SUITES = "ping ssh parsec" +``` +- Build security-parsec-image image +```bash +bitbake security-parsec-image +``` +- Run tests +```bash +bitbake security-parsec-image -c testimage +``` + +Output of a successfull tests run should look similar to: +``` +RESULTS: +RESULTS - ping.PingTest.test_ping: PASSED (0.05s) +RESULTS - ssh.SSHTest.test_ssh: PASSED (0.25s) +RESULTS - parsec.ParsecTest.test_all_providers: PASSED (1.84s) +RESULTS - parsec.ParsecTest.test_pkcs11_provider: PASSED (2.91s) +RESULTS - parsec.ParsecTest.test_tpm_provider: PASSED (3.33s) +SUMMARY: +security-parsec-image () - Ran 5 tests in 8.386s +security-parsec-image - OK - All required tests passed (successes=5, skipped=0, failures=0, errors=0) +``` + + +Manual testing with runqemu +=========================== + + This layer also contains a recipe for pasec-tool which can be used for +manual testing of the Parsec service: + + IMAGE_INSTALL:append = " parsec-tool" + + There are a series of Parsec Demo videos showing how to use parsec-tool +to test the Parsec service base functionality: +https://www.youtube.com/watch?v=ido0CyUdMHM&list=PLKjl7IFAwc4S7WQqqphCsyy6DPDxJ2Skg&index=4 + + The parsec-tool recipe also includes `parsec-cli-tests.sh` script +which runs e2e tests against all providers enabled and configured +in Parsec service. + + You can use runqemu to start a VM with a built image file and run +manual tests with parsec-tool. + +Enabling Parsec providers for manual testing +============================================ + +1. MbedCrypto provider + The default Parsec service config file contains the MbedCrypto provider +enabled. No changes required. + +2. PKCS11 provider + The Software HSM can be used for manual testing of the provider by +including it into your test image: + + IMAGE_INSTALL:append = " softhsm" + +Inside the running VM: +- Stop Parsec +```bash +systemctl stop parsec +``` +- Initialise a token and notice the result slot number +```bash +softhsm2-util --init-token --slot 0 --label "Parsec Service" --pin 123456 --so-pin 123456 +``` +- Change the token ownership: +```bash +for d in /var/lib/softhsm/tokens/*; do chown -R parsec $d; done +``` +- Enable the PKCS11 provider and update its parameters in the Parsec config file +/etc/parsec/config.toml +``` +library_path = "/usr/lib/softhsm/libsofthsm2.so" +slot_number = <slot number> +user_pin = "123456" +``` +- Start Parsec +```bash +systemctl start parsec +``` + +3. TPM provider + The IBM Software TPM service can be used for manual testing of the provider by +including it into your test image: + + IMAGE_INSTALL:append = " swtpm tpm2-tools libtss2 libtss2-tcti-mssim" + +Inside the running VM: +- Stop Parsec +```bash +systemctl stop parsec +``` +- Start and configure the Software TPM server +```bash + /usr/bin/tpm_server & + sleep 5 + /usr/bin/tpm2_startup -c -T mssim + /usr/bin/tpm2_changeauth -c owner tpm_pass +``` +- Enable the TPM provider and update its parameters in the Parsec config file +/etc/parsec/config.toml +``` +tcti = "mssim" +owner_hierarchy_auth = "hex:74706d5f70617373" +``` +- Start Parsec +```bash +systemctl start parsec +``` + +Maintenance +----------- + +Send pull requests, patches, comments or questions to yocto-patches@lists.yoctoproject.org + +When sending single patches, please using something like: +'git send-email -1 --to yocto-patches@lists.yoctoproject.org --subject-prefix=meta-parsec][PATCH' + +These values can be set as defaults for this repository: + +$ git config sendemail.to yocto-patches@lists.yoctoproject.org +$ git config format.subjectPrefix meta-parsec][PATCH + +Now you can just do 'git send-email origin/master' to send all local patches. + +Maintainers: Anton Antonov <Anton.Antonov@arm.com> + Armin Kuster <akuster808@gmail.com> + + +License +======= + +All metadata is MIT licensed unless otherwise stated. Source code included +in tree for individual recipes is under the LICENSE stated in each recipe +(.bb file) unless otherwise stated. |