From 3583a01649572168f9d50310a554aed0de509d0a Mon Sep 17 00:00:00 2001 From: Katrina Prosise Date: Mon, 8 Jan 2024 06:12:53 -0500 Subject: [PATCH] Cleanup factory-registration security rm page Style and readability fixes applied. The subsections had duplicate naming which I attempted to address accurately. Viewed rendered output. Ran linter. This commit applies to FFTK-2795 Signed-off-by: Katrina Prosise --- .../security/factory-registration-ref.rst | 137 ++++++++---------- 1 file changed, 59 insertions(+), 78 deletions(-) diff --git a/source/reference-manual/security/factory-registration-ref.rst b/source/reference-manual/security/factory-registration-ref.rst index a7d28d8d1..77f7ceecd 100644 --- a/source/reference-manual/security/factory-registration-ref.rst +++ b/source/reference-manual/security/factory-registration-ref.rst @@ -3,54 +3,43 @@ Manufacturing Process for Device Registration ============================================= -Device registration is an important step to ensure that only trusted and authorized devices can -connect to the Foundries.io™ infrastructure. ``lmp-device-auto-register`` works well when run manually, and can be configured -to auto register devices in **CI** -:ref:`builds `. However, -a different process is required for provisioning production devices. -The key to production provisioning lies in owning the -:ref:`device gateway PKI `. - -The :ref:`device gateway PKI ` serves as the trust anchor for all device communications. -When a device tries to connect to the Foundries.io gateway, it presents a TLS certificate. -Once a customer has -control of their PKI, they can create client TLS certificates for -devices that will be trusted by the Foundries.io device gateway. - -Customers all have unique requirements, so Foundries.io created a -`reference implementation`_ that customers can fork and modify to -their liking. By using this example, customers can authenticate -and register devices, granting them the necessary certificates to be -trusted by the Foundries.io gateway. Here are some common ways to use this reference. +Device registration is important in ensuring that only trusted and authorized devices can connect to the Foundries.io™ infrastructure. +``lmp-device-auto-register`` works well manually, and can be configured to auto register devices in **CI** :ref:`builds `. +However, a different process is required for provisioning production devices. +The key to production provisioning lies in owning the :ref:`device gateway PKI `. + +The device gateway PKI serves as the trust anchor for all device communications. +A device presents a TLS certificate when it tries to connect to the Foundries.io gateway. +With control of your PKI, you can create client TLS certificates that will be trusted by the Foundries.io device gateway. + +Everyone will have unique requirements, so Foundries.io created a `reference implementation`_ that you can fork and modify to your liking. +Using this example, you can authenticate and register devices, granting them the necessary certificates to be trusted by the Foundries.io gateway. +This page covers some common ways to use this reference. .. _ref-fully-detached: -Fully detached +Fully Detached -------------- -In this scenario devices connect to a reference server instance on -a private network. This network is isolated from the internet -(api.foundries.io). Devices get a valid signed client certificate from -the reference server. Each device will be created via api.foundries.io -**on-the-fly** the first time they connect. -This scenario is handy for certain security constrained setups. However, -it does have a couple of potential drawbacks: +In this scenario, devices connect to a reference server instance on a private network. +This network is isolated from the internet (``api.foundries.io``). +Devices get a valid signed client certificate from the reference server. +Each device will be created **on-the-fly** via ``api.foundries.io`` the first time they connect. + +This is handy for certain security constrained setups. +However, it does have a couple caveats: - * Devices don't show up on Foundries.io until the first time - they connect. + * Devices do not show up on Foundries.io until they connect the first time. - * Devices won't have Foundries.io managed configuration data available - until this first connection. + * Devices will not have Foundries.io managed configuration data available until this first connection. .. note:: - Because devices are created on-the-fly, the backend maintains a - deny-list for device UUIDs that get deleted. This can lead to - confusion when trying to re-use a denied UUID in a FoundriesFactory using - HSMs. The standard ``lmp-device-register`` flow with the Foundries.io backend - will remove the denied device. However, in the "fully detached" - scenario, a user will need to manage the deny list themselves. The - deny list can be managed with: + Because devices are created on-the-fly, the backend maintains a deny-list for device UUIDs that get deleted. + This can lead to confusion when trying to re-use a denied UUID in a Factory using HSMs. + The standard ``lmp-device-register`` flow with the Foundries.io backend will remove the denied device. + However, in the "fully detached" scenario, you will need to manage the deny list yourself. + The deny list can be managed with: * ``fioctl devices list-denied`` * ``fioctl devices delete-denied`` @@ -58,35 +47,29 @@ it does have a couple of potential drawbacks: Registering Production Device by Default ---------------------------------------- -After the development cycle is over, and it is expected that every new -device to be registered is a production device, it might be good to enable this -by default in LmP. +After the development cycle, when every device to be registered is a production device, it may be good to enable this by default in LmP. -Create or modify the ``lmp-device-register_%.bbappend`` file in the factory's -``meta-subscriber-overrides``: +Create or modify the ``lmp-device-register_%.bbappend`` file in the Factory's ``meta-subscriber-overrides``: -.. prompt:: bash host:~$ +.. code-block:: shell mkdir -p meta-subscriber-overrides/recipes-sota/lmp-device-register/ echo 'PACKAGECONFIG += "production"' >> meta-subscriber-overrides/recipes-sota/lmp-device-register/lmp-device-register_%.bbappend -The images created with this configuration includes ``PRODUCTION=on`` by default -on the command ``lmp-device-register``. +Images created with this configuration include ``PRODUCTION=on`` for the command ``lmp-device-register``. -This is very usefully when the update plan is to use -:ref:`ref-production-targets`. +This is useful when the update plan is to use :ref:`ref-production-targets`. + +``lmp-device-auto-register`` Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -lmp-device-auto-register configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Devices can also have :ref:`ug-lmp-device-auto-register` enabled. -In order to have the device run ``lmp-device-register`` automatically -on boot. +This is needed in order for a device to automatically run ``lmp-device-register`` on boot. -After following those steps a FoundriesFactory can copy `lmp-device-auto-register`_ into their -meta-subscriber-overrides.git production branch as -``recipes-support/lmp-device-auto-register/lmp-device-auto-register/lmp-device-auto-register`` -and add the following two environment variables to that specific file at -the top for example:: +Copy `lmp-device-auto-register`_ into your Factory's ``meta-subscriber-overrides.git`` production branch as: +``recipes-support/lmp-device-auto-register/lmp-device-auto-register/lmp-device-auto-register``. +Add the following two environment variables at the top of the file: +:: #!/bin/sh -e @@ -97,29 +80,27 @@ the top for example:: ... -Then it will use the reference server as the one where to register instead -of using https://api.foundries.io. +It will now use the reference server to register, instead of ``https://api.foundries.io``. -Registration reference configuration +Registration Reference Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The registration reference should work out-of-the box for this scenario. -The operator simply needs to copy their PKI keys as described in the -reference server's `README.md`_. +You only need to copy you PKI keys as described in the reference server's `README.md`_. -Partially detached +Partially Detached ------------------ -In this scenario devices connect to a reference server instance on -a private network, but the reference server has access to -api.foundries.io. The reference server can create device entries via -api.foundries.io as devices are registered. -Additionally, if devices have access to ota-lite.foundries.io:8443, -they can download their initial fioconfig configuration data. +In this scenario, devices connect to a reference server instance on a private network. +However, this time the reference server has access to ``api.foundries.io``. +The reference server can create device entries via ``api.foundries.io`` as devices are registered. -lmp-device-auto-register configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A factory can also customize the ``lmp-device-auto-register`` as is -explained in :ref:`ug-lmp-device-auto-register`. +Additionally, if devices have access to ``ota-lite.foundries.io:8443``, they can download their initial fioconfig data. + +Partially Detached ``lmp-device-auto-register`` Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A factory can also customize ``lmp-device-auto-register`` as is explained in :ref:`ug-lmp-device-auto-register`. For example:: @@ -153,12 +134,12 @@ For example:: #systemctl start aktualizr-lite #systemctl start fioconfig -Registration reference configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Partially Detached Registration Reference Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The registration reference should work out-of-the box for this scenario. -The operator will need to create a Foundries.io API token with scope -``devices:create``. They can take this token and configure the -reference server as per the README.md. +The operator will need to create a Foundries.io API token with scope ``devices:create``. +They can take this token and configure the reference server as per the ``README.md``. .. _reference implementation: https://github.com/foundriesio/factory-registration-ref