Skip to content

Commit

Permalink
Cleanup factory-registration security rm page
Browse files Browse the repository at this point in the history 
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 <[email protected]>
  • Loading branch information
@kprosise
kprosise committed Jan 9, 2024
1 parent 71ca155 commit 3583a01
Showing 1 changed file with 59 additions and 78 deletions.
137 changes: 59 additions & 78 deletions source/reference-manual/security/factory-registration-ref.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,90 +3,73 @@
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 <ug-lmp-device-auto-register>`. However,
a different process is required for provisioning production devices.
The key to production provisioning lies in owning the
:ref:`device gateway PKI <ref-device-gateway>`.

The :ref:`device gateway PKI <ref-device-gateway>` 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 <ug-lmp-device-auto-register>`.
However, a different process is required for provisioning production devices.
The key to production provisioning lies in owning the :ref:`device gateway PKI <ref-device-gateway>`.

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``

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``.

Check failure on line 70 in source/reference-manual/security/factory-registration-ref.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'", "location": {"path": "source/reference-manual/security/factory-registration-ref.rst", "range": {"start": {"line": 70, "column": 19}}}, "severity": "ERROR"}
Add the following two environment variables at the top of the file:
::

#!/bin/sh -e

Expand All @@ -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::

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 3583a01

Please sign in to comment.