diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8604e51..b968353 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,9 @@ + + # Contributing to the ot-sku repository ## Contributor License Agreement diff --git a/README.md b/README.md index 945324e..f053b93 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,88 @@ + + # ot-sku -This repository defines the configuration for the OpenTitan Earlgrey Open-Market -SKU. This repository is meant to be linked into the upstream opentitan -repository (branch `earlgrey_1.0.0`) by the `PROV_EXTS_DIR` environment variable. +## About this repository + +This repository defines the configuration for the OpenTitan Earlgrey Open-Market SKU. +This repository is meant to be linked into the upstream `opentitan` repository (the [`earlgrey_1.0.0`](https://github.com/lowRISC/opentitan/tree/earlgrey_1.0.0) branch) by overriding the `ot_provisioning_exts` module. + +The file `skus/cfg.bzl` contains the top-level configuration data for this repository. +The `opentitan` repository will use this configuration to configure the provisioning firmware and test targets for the SKUs defined in `cfg.bzl`. + +OpenTitan is administered by [lowRISC CIC](https://www.lowrisc.org) as a collaborative project to produce high quality, open IP for instantiation as a full-featured product. +See the [OpenTitan site](https://opentitan.org) and [OpenTitan docs](https://opentitan.org/book/) for more information about the project. + +## Getting Started + +The main usage of this repository will come through automated Github workflows - as such, it is not anticipated that much local development will be necessary. +If this *is* needed, most required tooling is packaged by [Bazel](https://bazel.build/). +The recommended development flow is to install [Bazelisk](https://github.com/bazelbuild/bazelisk), which will automatically manage bazel versions for you. + +Since this repository hooks into OpenTitan, you may need to install many of the dependencies that are required by OpenTitan if you want to manually run the automated flows. +See OpenTitan's "[Getting started](https://opentitan.org/book/doc/getting_started/index.html)" documentation for more information. -The file `skus/cfg.bzl` contains the toplevel configuration data for this -repository. The opentitan repository will use this configuration to configure -the provisioning firmware and test targets for the SKUs in `cfg.bzl`. ### Example + ```sh git clone https://github.com/lowRISC/opentitan git clone https://github.com/lowRISC/ot-sku -export PROV_EXTS_DIR=${PWD}/ot-sku/skus +# Here we capture the repeated override arg in an environment variable. +# You might want to consider using this in a .bazelrc file instead. +export BAZEL_OVERRIDE_ARGS=--override_module=ot_provisioning_exts=${PWD}/ot-sku cd opentitan +git fetch origin earlgrey_1.0.0 +git checkout earlgrey_1.0.0 # Now you can perform your builds or tests -bazel test --test_output=streamed //sw/host/provisioning/orchestrator/tests:e2e_multistage_ot00_staging_hyper310_test +bazelisk test ${BAZEL_OVERRIDE_ARGS} --test_output=streamed //sw/host/provisioning/orchestrator/tests:e2e_multistage_ot00_staging_hyper310_test + +bazelisk build ${BAZEL_OVERRIDE_ARGS} @provisioning_exts//open/rom_ext:rom_ext_dice_x509_prod_slot_virtual +``` + +## Creating Releases + +GitHub [releases](https://github.com/lowRISC/ot-sku/releases) are used to automate the majority of the signing flows. +For more detailed documentation covering how to create a release, see [`doc/create_release.md`](doc/create_release.md). +For developers that are making changes to or maintaining the release flow, see some additional developer documentation in [`doc/create_release_dev.md`](doc/create_release_dev.md). + +For the signing operation, you will need to run [`hsmtool`](https://opentitan.org/earlgrey_1.0.0/book/sw/host/hsmtool/index.html). +At the time of writing, this can be acquired from the [`earlgrey_1.0.0`](https://github.com/lowRISC/opentitan/tree/earlgrey_1.0.0) branch of OpenTitan by running the following from your local copy: -bazel build @provisioning_exts//open/rom_ext:rom_ext_dice_x509_prod_slot_virtual +```sh +bazelisk build //sw/host/hsmtool ``` + +You can either run this directly with `bazelisk run`, or use `bazelisk cquery` to find the output binary and copy it elsewhere. + +A separate version of `hsmtool` is also maintained in the [opentitan-signing-infra](https://github.com/lowRISC/opentitan-signing-infra) repository. +To acquire `hsmtool` from this repository, you can run: + +```sh +bazelisk build //hsmtool +``` + + +In the future, it is planned to migrate all OpenTitan implementations to use this separate repository, and the above will be deprecated. + +### Testing + +This repository is currently still being setup, and as such [SoftHSMv2](https://github.com/softhsm/SoftHSMv2) is being used as a software HSM to **test** the release and signing flows. +If you are intending on using these testing flows, you can find more relevant documentation about configuring SoftHSM [here](skus/open/fake_keygen/README.md). + +## Licensing + +Unless otherwise noted, everything in this repository is covered by the Apache License, Version 2.0 (see [LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt) for the full text). + +## Read More + +* [Contribution Guide](CONTRIBUTING.md) +* [Guidance for reporting security vulnerabilities](https://github.com/lowRISC/opentitan/blob/master/SECURITY.md) +* [Guidance for creating release flows](doc/create_release.md) diff --git a/doc/create_release.md b/doc/create_release.md index 3afb00c..99c20f4 100755 --- a/doc/create_release.md +++ b/doc/create_release.md @@ -1,20 +1,28 @@ + + # Creating a release Creating a release of the provisioning and ROM_EXT artifacts is a multi-step process, most of which is automated using Github Actions. -This document covers the user-facing part of the release flow. See also the [Developer documentation](create_release_dev.md). +This document covers the user-facing part of the release flow. +See also the [Developer documentation](create_release_dev.md) for guidance on maintaining & developing this workflow. ## Step 1: creating pre-signing release artifacts -The first step consists in building the pre-sign artifacts. This step is completely automated using Github Actions. -- Select the `Create release` workflow in the `Actions` of the repository. +The first step consists of building the pre-signing artifacts. +This step is completely automated using Github Actions. +- Select the `Create a release` workflow in the `Actions` tab of the repository. ![Image of Github UI showing the Actions page](presign_release_step1a.png) -- Click on the `Run workflow` button and fill out the parameters of the release. Most parameters should be clear. +- Click on the `Run workflow` dropdown and fill out the parameters of the release - most parameters should be clear: - The tag will be used to tag the release of the pre-signing artifacts (the final release uses a different tag). - It supports using any OpenTitan repository and/or branch which is compatible with the `earlgrey_1.0.0` branch. The default choice is `lowRISC/opentitan` and `earlgrey_1.0.0`. - - Make sure to choose an appropriate **release branch name**. In particular, if you are doing a real release, - make sure that this branch is covered by the **branch protection rules**. It is suggested to make your branch - name start with `release_`. + - Make sure to choose an appropriate **release branch name**. + > ⚠️ In particular, if you are doing a real release, make sure that this branch is covered by the **branch protection rules**. + > It is suggested to make your branch name start with `release_` and to protect all such branches. ![Image of Github UI showing the workflow parameters](presign_release_step1b.png) - If the workflow runs successfully, a release will be created with the pre-signing artifacts. @@ -22,45 +30,72 @@ The first step consists in building the pre-sign artifacts. This step is complet ## Step 2: signing the artifacts -Signing the artifacts is a manual, typically off-line, step. -The `presign_perso.tar.xz` and `presign_rom_ext.tar.xz` archives contains the digests and `hsmtool` instructions to execute. +Signing the artifacts is a manual step that typically occurs in an offline environment. +The `presign_perso.tar.xz` and `presign_rom_ext.tar.xz` archives provided by the release contain the digests and relevant `hsmtool` instructions to execute. This flow typically looks like this: ```bash -# Setup hsmtool environment to use either SoftHSM or a real HSM. -# Download presign_perso.tar.xz and presign_rom_ext.tar.xz -# Extract then. +# Setup the SKU that you are making a release for: +export OT_SKU=ot00 +export OT_SKU_PATH=/path/to/your/ot-sku +export HSMTOOL=/path/to/your/hsmtool + +# Setup your hsmtool environment to use either SoftHSM or a real HSM. +# Download presign_perso.tar.xz and presign_rom_ext.tar.xz from the pre-signing release created in step (1) and verify their hashes. +# When you are happy with the contents and have prepared your environment, extract the archives: mkdir presign_perso presign_rom_ext tar -xvf presign_perso.tar.xz -C presign_perso tar -xvf presign_rom_ext.tar.xz -C presign_rom_ext -# Execute signing. + +# Ensure that the expected signature files are present, and then execute the signing. pushd presign_perso -/path/to/hsmtool $HSMTOOL_CUSTOM_ARG exec provisioning_ot00.json +$HSMTOOL $HSMTOOL_CUSTOM_ARG exec provisioning_${OT_SKU}.json popd pushd presign_rom_ext -/path/to/hsmtool $HSMTOOL_CUSTOM_ARG exec rom_ext.json +$HSMTOOL $HSMTOOL_CUSTOM_ARG exec rom_ext.json popd + # Checkout the release branch of ot-sku repository. git checkout # Copy the signatures to the repository. -cp presign_perso/*_sig /path/to/ot-sku/skus/open/signatures/perso/ -cp presign_rom_mext/*_sig /path/to/ot-sku/skus/open/signatures/rom_ext/ -# Commit the signature (and usually a signing ceremony log). -git commit -vas -# Push the signature to the release branch via a PR. +cp presign_perso/*_sig ${OT_SKU_PATH}/skus/open/signatures/perso/ +cp presign_rom_ext/*_sig ${OT_SKU_PATH}/skus/open/signatures/rom_ext/ + +# Prepare the signing artifacts. First, stage the signature files. +# These are protected by `.gitignore` to avoid unintentionally committing signatures, so you must manually add them with `--force`. +# Make sure you check that the files staged for commit are correct! +git add --force ${OT_SKU_PATH}/skus/open/signatures/* +# Add a signing ceremony log under e.g. `logs/20XX-XX-XX.md` +git add +# Commit the signing artifacts +git commit -vs + +# Push the signature to the release branch (e.g. via a PR). git push ``` -At the end of this step, the release branch must contain the correct signatures in the `skus/open/signatures/perso/` -and/or `skus/open/signatures/rom_ext` repositories. +At the end of this step, the release branch must contain the correct signatures in the `skus/open/signatures/perso/` and/or `skus/open/signatures/rom_ext` directories. ## Step 3: create the post-signing release artifacts -This step consists in building the final artifacts and release. This step is completely automated using Github Actions. -- Select the `Create release` workflow in the `Actions` of the repository. +This step consists of building the final artifacts and releasing them. +It is completely automated using Github Actions. +- Select the `Create a release` workflow in the `Actions` tab of the repository. ![Image of Github UI showing the Actions page](presign_release_step1a.png) -- Click on the `Run workflow` button and fill out the parameters of the release. Most parameters should be clear. - - **Importantly** make sure that you run the flow the release branch! +- Click on the `Run workflow` dropdown and fill out the parameters of the release. + Most parameters should be **automatically** filled out for you - but you should verify that these all contain the correct information. + + > ⚠️ Most importantly, make sure that you select to run the workflow from the release branch! + > This is the same branch that was created in step (1), and which you pushed the signing artifacts to in step (2). ![Image of Github UI showing the workflow parameters](postsign_release_step1.png) - If the workflow runs successfully, a release will be created with the final artifacts. ![Image of Github UI showing the release artifacts](postsign_release_step2.png) + +## Troubleshooting + +If you run into Bazel errors in the Github Actions that are responsible creating for the releases, it is advised to check the following: +1. Check that the `ot-sku` repository has not fallen out of sync with changes to the OpenTitan branch you are creating a release for. + Ideally, these should stay the same - but it may be possible that upstream changes have caused these to become out of sync. +2. Ensure that the SKU configuration within this `ot-sku` repository is set up correctly. + +For errors related to GitHub, see the [developer documentation](create_release_dev.md) - you may need to ensure that the required Github token is set up correctly and has not expired. diff --git a/doc/create_release_dev.md b/doc/create_release_dev.md index 673434b..109db4b 100755 --- a/doc/create_release_dev.md +++ b/doc/create_release_dev.md @@ -1,23 +1,29 @@ + + # Creating a release (developer documentation) -The [release flow](.github/workflows/release.yml) has a few peculiarities which developers should be aware of. +The [release flow](../.github/workflows/release.yml) has a few peculiarities which developers should be aware of. This document lists the most important aspects. ## Self-modifying flow In order to avoid user errors, the release flow tries to enforce that the same parameters are used for the pre-signing and post-signing flow. This is achieved by having the release flow modify itself in the release branch to change the default parameters. -Concretely, certains values (which are identified by anchors of the form `<<< ANCHOR >>>`) are modified when doing the pre-signing flow. -This requires more permissions than typically available with the default Github action token and therefore requires a custom token (see below). +Concretely, certain values (which are identified by anchors of the form `<<< ANCHOR >>>`) are modified when doing the pre-signing flow. +This requires more permissions than are typically available with the default Github action token and therefore requires a custom token (see below). ## Custom Github token -The release flow requires that a Github token be added to the secrets of the repository under the name `RELEASE_TOKEN`. This token must have -the following rights: +The release flow requires that a Github token be added to the secrets of the repository under the name `RELEASE_TOKEN`. +This token must have the following rights: - **Read** access to metadata - **Read** and **Write** access to code and workflows ## Branch protection -It is highly recommended to set up branch protection so that release branches are automatically protected. The suggested setup -is to automatically protect branches started with `release_`. +It is highly recommended to set up branch protection so that release branches are automatically protected. +The suggested setup is to automatically protect branches started with `release_`. diff --git a/logs/README.md b/logs/README.md new file mode 100644 index 0000000..7aa7050 --- /dev/null +++ b/logs/README.md @@ -0,0 +1,10 @@ + + +# Signing Ceremony Logs + +This subdirectory contains logs of the HSM operations performed for signing ceremonies. +When new releases are created and HSM operations are performed, relevant logs should be added to this sub-directory and noted here. diff --git a/skus/open/fake_keygen/README.md b/skus/open/fake_keygen/README.md index 8b3799b..4e8372e 100644 --- a/skus/open/fake_keygen/README.md +++ b/skus/open/fake_keygen/README.md @@ -1,3 +1,9 @@ + + # Open Market SKU Keygen Templates This subdirectory contains `hsmtool` templates for generating the key material diff --git a/skus/open/keys/ca/README.md b/skus/open/keys/ca/README.md index ea61e40..91fe1e7 100644 --- a/skus/open/keys/ca/README.md +++ b/skus/open/keys/ca/README.md @@ -1,3 +1,9 @@ + + # DICE CA key and certificate This subdirectory contains the ECDSA public CA key and a self signed diff --git a/skus/open/keys/owner/README.md b/skus/open/keys/owner/README.md index 85834ec..feec60b 100644 --- a/skus/open/keys/owner/README.md +++ b/skus/open/keys/owner/README.md @@ -1,3 +1,9 @@ + + # Owner and application keys The keys in this directory are the owner and application keys for the manufacturing owner.