diff --git a/README.md b/README.md index e660af1..0f333cb 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ These recipes have been tested using these versions of yocto: - Dunfell (v3.1) - Zeus (v3.0) - Thud (v2.6) -- Sumo (v2.5) +- Sumo (v2.5) The wolfSSL library recipe is also included in the openembedded meta-networking layer, located [here](https://github.com/openembedded/meta-openembedded/tree/master/meta-networking/recipes-connectivity/wolfssl). @@ -52,7 +52,8 @@ git clone https://github.com/wolfSSL/meta-wolfssl.git After installing your build's Yocto/OpenEmbedded components: -1. Insert the 'meta-wolfssl' layer location into your build's bblayers.conf +1. Insert the 'meta-wolfssl' layer in `build/conf/bblayers.conf` location + into your build's bblayers.conf file, in the BBLAYERS section: ``` @@ -65,20 +66,20 @@ After installing your build's Yocto/OpenEmbedded components: 2. Once the 'meta-wolfssl' layer has been added to your BBLAYERS collection, you have two options - - 1. If you want to directly add wolfSSL recipes to your image recipe + + 1. If you want to directly add wolfSSL recipes to your image recipe proceed to step 3. - 2. If you want to run `bitbake wolf*` on a particular recipe then it needs + 2. If you want to run `bitbake wolf*` on a particular recipe then it needs to be added to the IMAGE_INSTALL. - This can be done by adding the following line to `local.conf` located in - `path/to/poky/build/conf`. + This can be done by adding the following line to `local.conf` located in + `path/to/poky/build/conf`. - For Dunfell and newer versions of Yocto: ``` IMAGE_INSTALL:append = " wolfssl wolfssh wolfmqtt wolftpm " ``` - + - For versions of Yocto older than Dunfell: ``` @@ -95,14 +96,14 @@ After installing your build's Yocto/OpenEmbedded components: 3. Edit your build's local.conf file to install the recipes you would like - to include (ie: wolfssl, wolfssh, wolfmqtt, wolftpm) - + to include (ie: wolfssl, wolfssh, wolfmqtt, wolftpm) + - For Dunfell and newer versions of Yocto ``` IMAGE_INSTALL:append = " wolfssl wolfssh wolfmqtt wolftpm wolfclu " ``` - + - For versions of Yocto older than Dunfell ``` IMAGE_INSTALL_append = " wolfssl wolfssh wolfmqtt wolftpm wolfclu " @@ -112,8 +113,8 @@ After installing your build's Yocto/OpenEmbedded components: specific combination of recipes. If you did step 2.2 make sure you comment out recipes that you don't desire - because leaving them uncommented may add unneed --enable-* options in your - build, which could increase the size of the build and turn on uneeded + because leaving them uncommented may add unneed --enable-* options in your + build, which could increase the size of the build and turn on uneeded features. Once your image has been built, the default location for the wolfSSL library @@ -198,8 +199,8 @@ This layer offers wolfSSL support for the following open source projects: - [curl](https://layers.openembedded.org/layerindex/recipe/5765/) - [OpenSSH](https://layers.openembedded.org/layerindex/recipe/5083/) -Example Application Recipes ---------------------------- +wolfSSL Example Application Recipes +----------------------------------- Several wolfSSL example application recipes are included in this layer. These include: @@ -253,10 +254,10 @@ Wolfssl-py and Wolfcrypt-py Installation Requirements To use the python wrapper for wolfSSL and wolfcrypt in a yocto build it will require python3, python3-cffi and wolfSSL are built on the target system. -If you are using older version of yocto (2.x) or (3.x), you will need to download +If you are using older version of yocto (2.x) or (3.x), you will need to download and add the meta-oe and meta-python recipes from openembedded's [meta-openembedded](https://github.com/openembedded/meta-openembedded) to the image. -It will be necassary then to make sure at minimum that the IMAGE_INSTALL:append +It will be necassary then to make sure at minimum that the IMAGE_INSTALL:append looks as follows: - For Dunfell and newer versions of Yocto @@ -290,11 +291,10 @@ looks as follows: Testing Wolfssl-py and Wolfcrypt-py ----------------------------------- - To test the python wrapper for wolfSSL and wolfcrypt in a yocto build it will require python3, python3-pytest, python3-cffi and wolfSSL are built on the target system. -It will be necassary then to make sure at minimum that the IMAGE_INSTALL:append +It will be necassary then to make sure at minimum that the IMAGE_INSTALL:append looks as follows: @@ -335,13 +335,74 @@ $ pytest This should then result in a pass or fail for the desired suit. -If you are testing this with the core-image-minimal yocto build, make sure +If you are testing this with the core-image-minimal yocto build, make sure to add a DNS server to /etc/resolv.conf like such with root perms ``` echo "nameserver 8.8.8.8" >> /etc/resolv.conf ``` +Running Image on the QEMU +------------------------- + +To run meta-wolfssl image on the QEMU (Quick EMUlator) you can follow these +general steps. For this example we will use the Yocto Project Poky. +Refer to: +[Yocto Project](https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html) for a detailed guide. + +1. Initialize the Build +This can be done by running these commands: + +``` +$ cd poky +$ source oe-init-build-env +``` + +This will initialize the build environment and let you run +bitbake in the build directory. + +2. Run bitbake +Next you can run bitbake to build the OS image that you want. Make sure +you have the correct variables added in the `local.conf` For this example +we will run `core-image-base`. Which can be built by running this comamnd +from the `build` directoy: + +``` +$ bitbake core-image-base +``` + +This will run bitbake and build the image with your added +meta-wolfssl recipes. + +3. Run the Image in QEMU +You can now simulate your image with the QEMU This can be done by running +the qemu that comes in your Yocto Project the default system is usually +`qemux86-64` but you can find what its set to by looking at your `local.conf`. +We can run this command to start the emulator: + +``` +$ runqemu qemux86-64 +``` + +4. Run Your Recipes +Now that you are in the QEMU you can navigate your way to the `usr/bin` +directory which contains the your wolfssl your applications. Lets say we +included these images in our `local.conf` + +``` +IMAGE_INSTALL:append = " wolfssl wolfcrypttest wolfcryptbenchmark " +``` + +In that case we can run wolfcrypttest and wolfcryptbenchmark examples from +the `usr/bin` directory like so: + +``` +$ ./wolfcrypttest +$ ./wolfcryptbenchmark +``` + +This will run the wolfcrypt test and benchmark examples from the QEMU. + wolfProvider ------------ To build wolfProvider view the instructions in this [README](recipes-wolfssl/wolfprovider/README.md) diff --git a/conf/layer.conf b/conf/layer.conf index cbb96d4..6a1d383 100644 --- a/conf/layer.conf +++ b/conf/layer.conf @@ -40,6 +40,11 @@ BBFILES += "${@bb.utils.contains('IMAGE_INSTALL', \ '${LAYERDIR}/recipes-wolfssl/wolftpm/*.bb ${LAYERDIR}/recipes-wolfssl/wolftpm/*.bbappend', \ '', d)}" +BBFILES += "${@bb.utils.contains('IMAGE_INSTALL', \ + 'wolftpm-wrap-test', \ + '${LAYERDIR}/recipes-examples/wolftpm/*.bb ${LAYERDIR}/recipes-examples/wolftpm/*.bbappend', \ + '', d)}" + BBFILES += "${@bb.utils.contains('IMAGE_INSTALL', \ 'wolfssl-py', \ '${LAYERDIR}/recipes-wolfssl/wolfssl-py/*.bb ${LAYERDIR}/recipes-wolfssl/wolfssl-py/*.bbappend', \ diff --git a/recipes-examples/wolftpm/README.md b/recipes-examples/wolftpm/README.md new file mode 100644 index 0000000..abd3c4e --- /dev/null +++ b/recipes-examples/wolftpm/README.md @@ -0,0 +1,205 @@ +wolfTPM Examples and Testing +============================ + +wolfTPM wrap_test example is included in this layer, which demonstrates +the TPM wrapper API functionality. + +The recipes for these applications are located at: +``` +meta-wolfssl/recipes-examples/wolftpm/wolftpm_%.bbappend +meta-wolfssl/recipes-examples/wolftpm/wolftpm-wrap-test.bb +meta-wolfssl/recipes-examples/wolftpm/wolfssl_%.bbappend +``` + +You'll need to compile wolfTPM, wolfTPM wrap test example, and wolfSSL with +wolfTPM support. This can be done with these commands in the build directory: +``` +bitbake wolfssl +bitbake wolftpm +bitbake wolftpm-wrap-test +``` + +Adding Layers +------------- + +Besides adding meta-wolfssl to your bblayers.conf file, you will need to +add the following layers to your bblayers.conf file and clone +them into the poky directory. (Note: You need to have the same Yocto version +for all layers.) + +```bash +git clone https://github.com/openembedded/meta-openembedded.git -b +git clone https://git.yoctoproject.org/meta-security -b +``` + +Add the following layers to your bblayers.conf file: +```bash +BBLAYERS ?= " \ + /path/to/yocto/poky/meta-wolfssl \ + /path/to/yocto/poky/meta-security \ + /path/to/yocto/poky/meta-security/meta-tpm \ + /path/to/yocto/poky/meta-openembedded/meta-oe \ + /path/to/yocto/poky/meta-openembedded/meta-python \ + /path/to/yocto/poky/meta-openembedded/meta-networking \ + /path/to/yocto/poky/meta-openembedded/meta-perl \ + " +``` + +System Requirements +------------------- + +For Ubuntu/Debian systems, install the following packages: +```bash +sudo apt-get install python3-git python3-jinja2 python3-setuptools \ + swtpm swtpm-tools tpm2-tools git socat build-essential +``` + +Image Install Configuration +--------------------------- + +To install these applications into your image, you will need to edit your +`build/conf/local.conf` file and add the following: + +```bash +# Add TPM packages +IMAGE_INSTALL:append = " \ + tpm2-tools \ + tpm2-tss \ + libtss2 \ + libtss2-mu \ + libtss2-tcti-device \ + libtss2-tcti-mssim \ + wolfssl \ + wolftpm \ + wolftpm-wrap-test \ +" + +# Set the image link name +IMAGE_LINK_NAME = "core-image-minimal-qemux86-64" +# Enable security features +DISTRO_FEATURES:append = " security" +# Enable TPM support +DISTRO_FEATURES:append = " tpm tpm2" +# Enable kernel TPM support +KERNEL_FEATURES:append = " features/tpm/tpm.scc" +# Machine features +MACHINE_FEATURES:append = " tpm tpm2" +``` + +WolfTPM Configuration +--------------------- + +To add wolfTPM configurations you can add configurations to the +EXTRA_OECONF variable. We need to have --enable-devtpm for the TPM +simulator to work. You can enable debug logging and other configurations +like this: +``` +EXTRA_OECONF += "--enable-devtpm --enable-debug" +``` + +Testing with QEMU and TPM Simulator +----------------------------------- + +### Setting up Software TPM on Host Computer + +Follow these steps to setup the Software TPM on your host computer. This +will allow you to run the wolfTPM wrap test inside the QEMU. + +1. Compile your target image +``` +bitbake core-image-minimal +``` + +2. Clean up any existing TPM state: +``` +sudo killall swtpm 2>/dev/null +sudo rm -rf /tmp/mytpm1 +``` + +3. Create directory and set permissions: +``` +sudo mkdir -p /tmp/mytpm1 +sudo chown -R $(whoami):$(whoami) /tmp/mytpm1 +chmod 755 /tmp/mytpm1 +``` + +4. Start the TPM simulator (in terminal 1): +``` +sudo swtpm socket --tpmstate dir=/tmp/mytpm1 \ + --ctrl type=unixio,path=/tmp/mytpm1/swtpm-sock \ + --log level=20 \ + --tpm2 +``` + +5. Initialize the TPM (in terminal 2): +``` +sudo swtpm_setup --tpmstate /tmp/mytpm1 \ + --createek \ + --create-ek-cert \ + --create-platform-cert \ + --lock-nvram \ + --tpm2 +``` + +6. Fix permissions for QEMU access: +``` +sudo chown -R $(whoami):$(whoami) /tmp/mytpm1 +sudo chmod -R 755 /tmp/mytpm1 +sudo chmod 777 /tmp/mytpm1/swtpm-sock +``` + +7. Start and run the QEMU (in terminal 3): +``` +cd ~/poky/build +runqemu qemux86-64 nographic core-image-minimal \ + qemuparams="-chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \ + -tpmdev emulator,id=tpm0,chardev=chrtpm \ + -device tpm-tis,tpmdev=tpm0" +``` + +### Running wolfTPM wrap test on QEMU using Software TPM + +Now that the TPM is setup, we can run the wolfTPM wrap test inside the QEMU. + +1. Run the wolfTPM wrap test +``` +cd /usr/bin +./wolftpm-wrap-test +``` + +You should see the following output: +``` +root@qemux86-64:/usr/bin# ./wolftpm-wrap-test +TPM2 Demo for Wrapper API's +Mfg IBM (0), Vendor SW TPM, Fw 8217.4131 (0x163636), FIPS 140-2 0, CC-EAL4 0 +Found 2 persistent handles +Created new RSA Primary Storage Key at 0x81000200 +Creating a loaded new TPM 2.0 key Test Passed +RSA Sign/Verify using RSA PKCSv1.5 (SSA) padding +RSA Sign/Verify using RSA PSS padding +RSA Encrypt/Decrypt Test Passed +RSA Encrypt/Decrypt OAEP Test Passed +RSA Encrypt/Decrypt RSAES Test Passed +RSA Key 0x80000001 Exported to wolf RsaKey +wolf RsaKey loaded into TPM: Handle 0x80000000 +RSA Private Key Loaded into TPM: Handle 0x80000001 +Created new ECC Primary Storage Key at 0x81000201 +ECC Sign/Verify Passed +ECC DH Test Passed +ECC Verify Test Passed +ECC Key 0x80000001 Exported to wolf ecc_key +wolf ecc_key loaded into TPM: Handle 0x80000000 +ECC Private Key Loaded into TPM: Handle 0x80000001 +NV Test (with auth) on index 0x1800201 with 1024 bytes passed +NV Test on index 0x1800200 with 1024 bytes passed +Hash SHA256 test success +HMAC SHA256 test success +Encrypt/Decrypt (known key) test success +Encrypt/Decrypt test success +PCR Test pass +root@qemux86-64:/usr/bin# +``` + +Refer to the [wolfTPM Examples README](https://github.com/wolfSSL/wolfTPM/blob/master/examples/README.md) for more information on the examples directory. + +Refer to the [meta-wolfssl README](https://github.com/wolfSSL/meta-wolfssl/blob/master/README.md) for more information on setting up your layer. diff --git a/recipes-examples/wolftpm/wolfssl_%.bbappend b/recipes-examples/wolftpm/wolfssl_%.bbappend new file mode 100644 index 0000000..7562ce5 --- /dev/null +++ b/recipes-examples/wolftpm/wolfssl_%.bbappend @@ -0,0 +1,4 @@ +# wolfssl_%.bbappend + +# Enables wolfTPM support in wolfSSL +EXTRA_OECONF += "--enable-wolftpm" diff --git a/recipes-examples/wolftpm/wolftpm-wrap-test.bb b/recipes-examples/wolftpm/wolftpm-wrap-test.bb new file mode 100644 index 0000000..0b58dc3 --- /dev/null +++ b/recipes-examples/wolftpm/wolftpm-wrap-test.bb @@ -0,0 +1,46 @@ +#wolftpm-wrap-test.bb +SUMMARY = "wolfTPM Examples Directory" +DESCRIPTION = "wolfTPM examples directory used to demonstrate \ + features of a TPM 2.0 module" +HOMEPAGE = "https://www.wolfssl.com/products/wolftpm" +BUGTRACKER = "https://github.com/wolfssl/wolftpm/issues" +SECTION = "libs" + +LICENSE = "GPL-2.0-only" +LIC_FILES_CHKSUM = "file://LICENSE;md5=b234ee4d69f5fce4486a80fdaf4a4263" +S = "${WORKDIR}/git" +DEPENDS += "wolfssl" + +SRC_URI = "git://github.com/wolfssl/wolfTPM.git;nobranch=1;protocol=https;rev=bcf2647ebcf76e76a75cefc46f7187d213eb1fcd" + +do_configure[noexec] = "1" +do_compile[noexec] = "1" + +WOLFTPM_EXAMPLES_DIR = "${datadir}/wolftpm-test" +WOLFTPM_EXAMPLES_INSTALL_DIR = "${D}${WOLFTPM_EXAMPLES_DIR}" +WOLFTPM_EXAMPLES_README = "README.txt" +WOLFTPM_EXAMPLES_README_DIR = "${WOLFTPM_EXAMPLES_INSTALL_DIR}/${WOLFTPM_EXAMPLES_README}" + +python () { + distro_version = d.getVar('DISTRO_VERSION', True) + wofltpm_examples_dir = d.getVar('WOLFTPM_EXAMPLES_DIR', True) + wolftpm_examples_install_dir = d.getVar('WOLFTPM_EXAMPLES_INSTALL_DIR', True) + wolftpm_examples_readme_dir = d.getVar('WOLFTPM_EXAMPLES_README_DIR', True) + + bb.note("Installing dummy file for wolfTPM test example") + installDir = 'install -m 0755 -d "%s"\n' % wolftpm_examples_install_dir + makeDummy = 'echo "This is a dummy package" > "%s"\n' % wolftpm_examples_readme_dir + + d.appendVar('do_install', installDir) + d.appendVar('do_install', makeDummy) + + pn = d.getVar('PN', True) + if distro_version and (distro_version.startswith('2.') or distro_version.startswith('3.')): + files_var_name = 'FILES_' + pn + else: + files_var_name = 'FILES:' + pn + + current_files = d.getVar(files_var_name, True) or "" + new_files = current_files + ' ' + wofltpm_examples_dir + '/*' + d.setVar(files_var_name, new_files) +} diff --git a/recipes-examples/wolftpm/wolftpm_%.bbappend b/recipes-examples/wolftpm/wolftpm_%.bbappend new file mode 100644 index 0000000..114596e --- /dev/null +++ b/recipes-examples/wolftpm/wolftpm_%.bbappend @@ -0,0 +1,26 @@ +#wolftpm_%.bbappend +WOLFTPM_TEST_DIR = "${B}/examples/wrap/.libs" +WOLFTPM_TEST = "wrap_test" +WOLFTPM_TEST_YOCTO = "wolftpm-wrap-test" +WOLFTPM_INSTALL_DIR = "${D}${bindir}" + +# Configurations (--enable-devtpm is required for the TPM simulator to work) +EXTRA_OECONF += "--enable-devtpm" + +python () { + # Get the environment variables WOLFTPM_TEST_DIR, WOLFTPM_TEST, + # WOLFTPM_TEST_YOCTO, and WOLFTPM_INSTALL_DIR + wolftpm_test_dir = d.getVar('WOLFTPM_TEST_DIR', True) + wolftpm_test = d.getVar('WOLFTPM_TEST', True) + wolftpm_test_yocto = d.getVar('WOLFTPM_TEST_YOCTO', True) + wolftpm_install_dir = d.getVar('WOLFTPM_INSTALL_DIR', True) + + bbnote = 'bbnote "Installing wolfTPM wrap_test"\n' + installDir = 'install -m 0755 -d "%s"\n' % (wolftpm_install_dir) + cpWrapTest = 'cp "%s/%s" "%s/%s"\n' % (wolftpm_test_dir, wolftpm_test, + wolftpm_install_dir, wolftpm_test_yocto) + + d.appendVar('do_install', bbnote) + d.appendVar('do_install', installDir) + d.appendVar('do_install', cpWrapTest) +}