diff options
Diffstat (limited to 'meta-parsec/README.md')
| -rw-r--r-- | meta-parsec/README.md | 140 |
1 files changed, 111 insertions, 29 deletions
diff --git a/meta-parsec/README.md b/meta-parsec/README.md index a2736b6..785c932 100644 --- a/meta-parsec/README.md +++ b/meta-parsec/README.md @@ -1,8 +1,7 @@ meta-parsec layer ============== -This layer contains recipes for the Parsec service with Mbed-Crypto, -Pkcs11 and TPM providers and parsec tools. +This layer contains recipes for the Parsec service and parsec tools. Dependencies ============ @@ -11,23 +10,12 @@ This layer depends on: URI: git://git.openembedded.org/meta-openembedded branch: master - revision: HEAD - prio: default URI git://git.yoctoproject.org/meta-security branch: master - revision: HEAD - prio: default - - URI https://github.com/meta-rust/meta-rust.git - branch: master - revision: HEAD - prio: default URI https://github.com/kraj/meta-clang.git branch: master - revision: HEAD - prio: default Adding the meta-parsec layer to your build ========================================== @@ -44,7 +32,6 @@ other layers needed. e.g.: /path/to/yocto/meta-yocto-bsp \ /path/to/meta-openembedded/meta-oe \ /path/to/meta-openembedded/meta-python \ - /path/to/meta-rust \ /path/to/meta-clang \ /path/to/meta-security/meta-tpm \ /path/to/meta-security/meta-parsec \ @@ -53,16 +40,38 @@ other layers needed. e.g.: To include the Parsec service into your image add following into the local.conf: - IMAGE_INSTALL_append = " parsec-service" + 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: - The Parsec service will be deployed into the image built with all the supported -providers and with the default config file from the Parsec repository: + 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 - The default Parsec service config file contains the MbedCrypto provider -enabled. The config file needs to be updated to use the Parsec service -with other providers like TPM or PKCS11. The required procedures are -covered in Parsec documentation. -https://parallaxsecond.github.io/parsec-book/ +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 ================ @@ -80,30 +89,103 @@ https://github.com/meta-rust/cargo-bitbake 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-tools" + 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 for manual testing. +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" + IMAGE_INSTALL:append = " softhsm" Inside the running VM: - Stop Parsec @@ -134,7 +216,7 @@ systemctl start parsec The IBM Software TPM service can be used for manual testing of the provider by including it into your test image: - IMAGE_INSTALL_append += " ibmswtpm2 tpm2-tools libtss2 libtss2-tcti-mssim" + IMAGE_INSTALL:append = " swtpm tpm2-tools libtss2 libtss2-tcti-mssim" Inside the running VM: - Stop Parsec @@ -162,14 +244,14 @@ systemctl start parsec Maintenance ----------- -Send pull requests, patches, comments or questions to yocto@yoctoproject.org +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@yoctoproject.org --subject-prefix=meta-parsec][PATCH' +'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@yoctoproject.org +$ 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. |