Skip to content

Commit

Permalink
doc: clarifications regards tuf keys
Browse files Browse the repository at this point in the history 
Signed-off-by: Camila Macedo <[email protected]>
  • Loading branch information
Camila Macedo committed Oct 3, 2023
1 parent 288bd30 commit 7bd0383
Showing 1 changed file with 180 additions and 19 deletions.
199 changes: 180 additions & 19 deletions source/reference-manual/security/offline-keys.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,20 +19,159 @@ makes it hard to perform known attacks by obtaining only one of the secrets.

FoundriesFactory provides the ability to manage TUF keys via dedicated `Fioctl™ <Fioctl_>`_ commands.

TUF Keys And Their Importance
============================================

The Update Framework (TUF) provides a method to secure software update systems.
Central to TUF's security model are keys, which are cryptographic tools used to sign
and verify the authenticity of updates. In the context of the Factory, there are two
key types to be familiar with:

**Root Key:**
Acts as the foundation of trust. This key signs metadata that declares which keys are
valid for other roles in the system. If compromised, an attacker could potentially
replace all other keys in the system.

**Targets Key:**
Used to sign metadata that lists actual updates (or "targets"). A compromised targets
key could allow an attacker to issue malicious updates.

TUF Roles And Their Importance
----------------------------------

The Update Framework (TUF) employs a hierarchy of roles to maintain the integrity and
security of software updates:

**Root Role:**

- Establishes trust for all other roles.
- Contains keys for other top-level roles.
- The foundation upon which trust for the entire system is built.

**Timestamp Role:**

- Ensures repository freshness.
- Points to the most recent snapshot.

**Snapshot Role:**

- Lists the latest versions of all update metadata.

**Targets Role:**

- Specifies available updates.
- Can delegate specific responsibilities to ensure granular control.

Each role has its unique purpose, and by keeping these roles separate,

Check warning on line 65 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 65, "column": 1}}}, "severity": "INFO"}
the system ensures that the compromise of one role doesn't jeopardize the entire

Check warning on line 66 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Contractions] Avoid Contractions: Use 'does not' not 'doesn't'.

Raw Output:
{"message": "[Fio-docs.Contractions] Avoid Contractions: Use 'does not' not 'doesn't'.", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 66, "column": 52}}}, "severity": "WARNING"}
update process.

How It All Comes Together
----------------------------------

Think of TUF as a secure delivery service:

- The **Root** is the trust anchor, like the headquarters of this service.
- The **Timestamp** is like a date stamp ensuring the package (update) is fresh.
- The **Snapshot** provides a summary of the packages in the warehouse.
- And the **Targets** are the details about each package, ensuring you get the right item securely.

The :ref:`Device Gateway <ref-ota-architecture>` checks each step, ensuring it gets a genuine, untampered update.
It's akin to a recipient verifying the authenticity and integrity of a parcel at every handover point, from the

Check warning on line 80 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Contractions] Avoid Contractions: Use 'it is' not 'It's'.

Raw Output:
{"message": "[Fio-docs.Contractions] Avoid Contractions: Use 'it is' not 'It's'.", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 80, "column": 1}}}, "severity": "WARNING"}
warehouse to their doorstep.

.. note::
We recommend running the command ``fioctl keys tuf updates review`` from time to time.
It will show you a list of our recommendations about improving your TUF usage, which evolve over time.
For example, it can show you the up to date information about the `Recommended Offline TUF Keys Schema`_.

How to Rotate Offline TUF Root Key
Online VS Offline Keys
-----------------------

**Online Keys:**

These are the keys that are stored on the servers and are accessible via the internet.
They are more prone to being compromised because they are connected to the internet and potentially susceptible
to a myriad of online attacks.

**Offline Keys:**

These keys are not connected to the internet. They are stored in a location that's offline.

Check warning on line 99 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Contractions] Avoid Contractions: Use 'that is' not 'that's'.

Raw Output:
{"message": "[Fio-docs.Contractions] Avoid Contractions: Use 'that is' not 'that's'.", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 99, "column": 77}}}, "severity": "WARNING"}
Being offline makes them much less susceptible to online attacks, making them more secure.

Why Rotate The TUF Root Key?
----------------------------

The TUF root key is the foundation of trust in the TUF system. It's essential to ensure that this key is as secure

Check warning on line 105 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Contractions] Avoid Contractions: Use 'it is' not 'It's'.

Raw Output:
{"message": "[Fio-docs.Contractions] Avoid Contractions: Use 'it is' not 'It's'.", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 105, "column": 64}}}, "severity": "WARNING"}
as possible. By taking the key offline, you're protecting it from a wide range of potential online attacks.

Rotating the key is the act of creating a new key and making it the active one. The rotation process involves several
steps to ensure a seamless transition and maintaining the integrity and trust of the TUF system.

Why Rotate Regularly?
-----------------------

Even when stored offline, keys can potentially be compromised. For instance, someone might gain physical
access to where they are stored, or there might be undetected vulnerabilities. Regular rotation ensures that even
if a key is compromised, its window of utility for malicious actors is limited.

Summary Of Steps:

Check failure on line 118 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Header-cap] 'Summary Of Steps:': Use APA title case: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case

Raw Output:
{"message": "[Fio-docs.Header-cap] 'Summary Of Steps:': Use APA title case: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 118, "column": 1}}}, "severity": "ERROR"}
-----------------------

Following a summary of the practical steps as an overview.

**Initial Setup:**

- The TUF root key is initially created online by Foundries.io™.
- The Factory admin using the following command should take the TUF roots key offline (`How to Rotate Offline TUF Root Key`_). **This is done as a one-time operation:**

fioctl keys tuf rotate-offline-key --role=root --first-time \

Check failure on line 128 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

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

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Fioctl' instead of 'fioctl'", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 128, "column": 3}}}, "severity": "ERROR"}
--keys=/absolute/path/to/root.keys.tgz

- The Factory admin must keep stored safe the ``root.keys.tgz`` of the keys which is created during this process. This backup (`Backup Offline TUF Keys`_) is vital for future operations and must be securely stored. Otherwise, it will no longer possible provide updates for the devices.

**Target Key Generation and Management:**

- After taking the TUF root key offline, the next important step is to manage the target keys which ensure the legitimacy of the updates. Use the following command to take the TUF targets key offline:

fioctl keys tuf rotate-offline-key --role=targets \

Check failure on line 137 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

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

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Fioctl' instead of 'fioctl'", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 137, "column": 3}}}, "severity": "ERROR"}
--keys=/absolute/path/to/root.keys.tgz --targets-keys=/absolute/path/to/targets.keys.tgz

- This command will generate the offline target keys (``targets.keys.tgz``) essential for signing the ``targets.json`` file. This ensures the authenticity and integrity of the updates. The ``targets.keys.tgz`` file, which results from this process, plays a crucial role when initiating weaves to advance Over-The-Air (OTA) updates for your devices. For instance, to create a weave, you must have the ``targets.keys.tgz`` to be used as for example in the following command:

fioctl wave init -k ~/path/to/keys/targets.only.key.tgz \

Check failure on line 142 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

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

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Fioctl' instead of 'fioctl'", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 142, "column": 5}}}, "severity": "ERROR"}

Check warning on line 142 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.em-dash] Did you mean to you use an em dash '—'?

Raw Output:
{"message": "[Fio-docs.em-dash] Did you mean to you use an em dash '—'?", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 142, "column": 21}}}, "severity": "WARNING"}
update-prod-02 \ # Name of your wave update

Check warning on line 143 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 143, "column": 9}}}, "severity": "INFO"}
42 \ # The target ID that you want to promote
prod \ # The device tag which represent the devices that should receive the OTA update

**Regular Rotations:**

- After the initial setup, the TUF root key should be rotated regularly. **(at the least yearly)**
- The same command without the flag `--first-time` should be used for these regular rotations.
- Again, a backup of the keys (`Backup Offline TUF Keys`_) should be created and stored securely after each rotation.

.. note::
In The Update Framework (TUF), the root key is the most critical, as it's the foundation for the trust chain.

Check warning on line 154 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Contractions] Avoid Contractions: Use 'it is' not 'it's'.

Raw Output:
{"message": "[Fio-docs.Contractions] Avoid Contractions: Use 'it is' not 'it's'.", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 154, "column": 73}}}, "severity": "WARNING"}
The targets key, on the other hand, is used to sign the ``targets.json`` which represents actual software updates.

It's wise to rotate the targets key regularly, but perhaps not as frequently as the root key.

Check warning on line 157 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Contractions] Avoid Contractions: Use 'it is' not 'It's'.

Raw Output:
{"message": "[Fio-docs.Contractions] Avoid Contractions: Use 'it is' not 'It's'.", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 157, "column": 4}}}, "severity": "WARNING"}
The logic here is that while a compromised targets key could allow malicious updates, those updates would only be

Check warning on line 158 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 158, "column": 4}}}, "severity": "INFO"}
considered valid for as long as that key is valid. Once you notice a malicious update, you would cancel the rollout
weave(s) which are using them, rotate the targets key to invalidate it and create new weave(s) with the new
Target keys to provide OTA updates. Depending on the threat model, some organizations might rotate the targets key
with every update, while others might do it on a set schedule (e.g., quarterly, bi-annually).

Now, check the further sections for a deeper understand of those operations.

How To Rotate Offline TUF Root Key
----------------------------------

The TUF root key is the most important key in TUF.
The owner of this key can sign TUF ``root.json`` which defines what keys and roles your Factory devices can trust.

The initial TUF root key for your Factory is generated by Foundries.io™, and it is stored online on our servers.
The Factory admin must take that key offline by rotating it as soon as possible.
Thereafter, that (offline) TUF root key must be rotated regularly (at the least yearly) to keep your Factory secure.
The initial TUF root key for your Factory is generated by Foundries.io™ as described above, and it is stored online on our servers.
**The Factory admin must take that key offline by rotating it as soon as possible.**
Thereafter, that (offline) TUF root key must be rotated regularly **(at the least yearly)** to keep your Factory secure.

.. note::
In the past, we used to send the TUF keys tarball via email to Factory owners at Factory creation.
Expand All @@ -58,23 +197,26 @@ Onwards, use a shorter command to rotate your (offline) TUF root key::
fioctl keys tuf rotate-offline-key --role=root --keys=/absolute/path/to/root.keys.tgz

.. note::
Here and below the ``root.keys.tgz`` file is the one created during the first offline TUF root key rotation.
Here and below the ``root.keys.tgz`` file is the one created during the first offline TUF root key rotation.

.. important::
You must create a backup of ``root.keys.tgz``

When rotating the TUF root key, the newly generated key is added to the keys tarball (``root.keys.tgz`` in examples).
That file **must never be lost**.
Otherwise, it will be impossible to make any future updates to the Factory TUF keys.
That will lead to the inability to deliver new :ref:`Over-the-Air (OTA) updates <ref-ota>` to your Factory devices.
Therefore, after each TUF root key rotation, we recommend that you `Backup Offline TUF Keys`_ as described below.
When rotating the TUF root key, the newly generated key is added to the keys tarball (``root.keys.tgz`` in examples).
That file **must never be lost**.
Otherwise, it will be impossible to make any future updates to the Factory TUF keys.
That will lead to the inability to deliver new :ref:`Over-the-Air (OTA) updates <ref-ota>` to your Factory devices.
Therefore, after each TUF root key rotation, we recommend that you `Backup Offline TUF Keys`_ as described below.

How to Rotate Offline TUF Targets Key
How To Rotate Offline TUF Targets Key
-------------------------------------

TUF has the notion of a ``targets.json`` file which specifies what updates (Targets) are available to Factory devices.
That file is automatically maintained by your Factory CI builds.
At the end of each build it is updated, signed by (online) TUF targets key, and pushed to Foundries.io servers.

Before going to production and creating the first :ref:`Wave and Production Targets <ref-production-targets>`,
a Factory owner must generate the offline TUF targets key.
a Factory owner must generate the ``offline TUF targets key``.

FoundriesFactory ensures that the Factory admins have exclusive control of updates to production devices.
To achieve this, it requires production ``targets.json`` files to be signed by two TUF targets keys:
Expand Down Expand Up @@ -108,11 +250,30 @@ This will perform the following steps:
That approach makes it possible to distribute the targets key among a wider set of Factory admins,
and allow them to sign production targets without exposing the TUF root key to the wider audience.

After each TUF targets key rotation we recommend that you `Backup Offline TUF Keys`_ as described below.
If you lose the offline TUF targets key, a new key can be generated if you have your Factory offline TUF root key.
However, losing this key may be inconvenient if more than one Factory admin can manage production targets.
.. important::

After each TUF targets key rotation we recommend that you `Backup Offline TUF Keys`_ as described below.
If you lose the offline TUF targets key, a new key can be generated if you have your Factory offline TUF root key.
However, losing this key may be inconvenient if more than one Factory admin can manage production targets.

The Need To View Offline TUF Keys
---------------------------------

Understanding when and why to view Offline TUF Keys is crucial for maintaining the security and trustworthiness of your update system. Here's a breakdown:

1. Why is it Important?

- Verification: Validating the integrity of updates requires making sure that the right keys are operational.
- Security Audit: Regularly inspecting the TUF keys ensures the Factory operates with optimal security and reduces risks of potential breaches.
- Troubleshooting: Should update-related issues arise, confirming the authenticity of keys becomes part of the resolution process.

2. When Should You Check?

- After Key Rotation: Once keys are rotated, it's pivotal to ascertain the new set is active and operational.
- Amidst Security Alerts: If there's any hint or evidence of a key compromise, you must conduct an immediate check to verify its authenticity.
- Routine Checks: Just like regular health check-ups, periodically inspect the keys as part of system maintenance and security hygiene.

How to View Offline TUF Keys
How To View Offline TUF Keys
----------------------------

The Factory's TUF metadata can be viewed using this Fioctl_ command::
Expand Down Expand Up @@ -163,7 +324,7 @@ See the section `How to Backup Offline TUF Keys`_ below, how the internal struct

.. _Backup Offline TUF Keys:

How to Backup Offline TUF Keys
How To Backup Offline TUF Keys
------------------------------

There are 3 recommended ways for backing up your Factory TUF keys:
Expand Down Expand Up @@ -194,7 +355,7 @@ Over time our engineers will add more items to that list as we develop new secur

.. _ref-offline-keys-more-than-1-root:

How to Add More Than 1 Offline TUF Keys
How To Add More Than 1 Offline TUF Keys
+++++++++++++++++++++++++++++++++++++++

Usually, you need to add more than 1 offline TUF signing key for your TUF roles in one of these use cases:
Expand Down Expand Up @@ -265,7 +426,7 @@ At any moment before applying the changes, and admin can cancel the transaction

Any user with admin rights can cancel the TUF root updates transaction, not only the one who initiated it.

How to Increase the TUF Signature Threshold
How To Increase the TUF Signature Threshold
+++++++++++++++++++++++++++++++++++++++++++

Requiring more than 1 offline signature for any TUF root changes greatly improves the TUF root role security.
Expand Down

0 comments on commit 7bd0383

Please sign in to comment.