Update Factory PKI docs according to recent changes #699

vkhoroz · 2024-04-04T13:31:21Z

PR Template and Checklist

This is an overhaul of two PKI related pages which are outdated for a long time already.

I added a lot of context to the Reference Manual, so that the user can now find all necessary information about PKI in one place.

Because of the above, quite some content was removed from the User Guide page about Factory PKI.
Instead, I improved on the original idea of that page to give more insights about how the PKI API works.
With these additions, we may now reference this updated User Guide to our users who want to integrate with the API directly.

Readiness

Merge (pending reviews)
Merge after date or event
Draft

Overview

Why merge this PR? What does it solve?

Checklist

Comments

Any thing else that a maintainer/reviewer should know.
This could include potential issues, rational for approach, etc.

vkhoroz · 2024-04-04T13:33:53Z

@vanmaegima @caiotpereira You've been working a lot recently with our users who integrate directly with the Factory PKI.

May you help me understand if the changes I make to our Factory PKI documentation will make that integration more clear?

vkhoroz · 2024-04-04T13:35:46Z

I'm going to check links on these pages after the docs are generated.
Also, I might add the "References" section to the bottom of each page, just like I was adding it to other pages.
It has taken me a lot of effort to compose those pages, so I wanted to get an early review before I spend time on links routine.

As for the vale errors - @kprosise we may want to improve our rule checkers.

kprosise · 2024-04-04T13:53:11Z

I'm going to check links on these pages after the docs are generated. Also, I might add the "References" section to the bottom of each page, just like I was adding it to other pages. It has taken me a lot of effort to compose those pages, so I wanted to get an early review before I spend time on links routine.

As for the vale errors - @kprosise we may want to improve our rule checkers.

Note that one of the link-check issues is related to a license change that I am waiting on. Regarding the vale errors, my guess is that a earlier syntax issue, such as a wrongly formed link or code-block is causing it to parse things incorrectly. This has been the case in the pass. I will check it out locally soon and see if I can figure out where the issue is.

doanac

this is great. thanks so much

doanac · 2024-04-04T15:01:24Z

source/reference-manual/security/device-gateway.rst

-You own the private key (NIST P-256 by default).
-The corresponding x509 certificate is shared with Foundries.io to define your root of trust.
+An X.509 certificate used as a Root Certificate Authority (RCA) for your Factory.
+You own the private key (NIST P-256 by default), and share the corresponding certificate with Foundries.io.


Suggested change

You own the private key (NIST P-256 by default), and share the corresponding certificate with Foundries.io.

You own the private key (NIST P-256 by default), and share the corresponding public certificate with Foundries.io.

Nixed.

A key can be public or private. A certificate is just a... certificate, bearing a public key. So it is presumed to be public.

source/reference-manual/security/device-gateway.rst

doanac · 2024-04-04T15:22:53Z

source/reference-manual/security/device-gateway.rst

+    Never lose your Factory Root of Trust, as Foundries.io does not own its copy and is not able to recover it.
+
+    We recommend storing your Factory Root of Trust in a cloud-based HSM solution, like e.g. `AWS Cloud HSM <https://aws.amazon.com/cloudhsm/>`_.
+    That way you get an increased safety of your highly important secret through their redundancy and backup policies.


do we? and if so, were do we document how to do it.

Some of our customers do store their Factory root private keys in the Cloud HSM.
I don't know if they used the --hsm-xxx options of Fioctl for that or not.
I'd like to get feedback from customer support on that.

As for documenting the HOW part, there are two options:

Do nothing.
The user may generate a private key without --hsm-xxx options, and then copy it into the HSM.
It is up to the HSM provider to document how to do that.

Document --hsm-xxx options in a separate section here.
Before doing that, I'd like to first verify our integration with e.g. AWS Cloud HSM, and write a blog post about that.

Currently, I have no capacity to do 2, so I decided that 1 is better than nothing.

I do not feel confident with only intructing our users to print private key and store in multiple safes.
The thing is: almost nobody does that, and when they lose the key - they come to blame on us.

A simple sentence to say they need to store a key in a cloud HSM will motivate them to do the research and offload this pain onto a billionaire business.

We can't recommend something and not provide documentation for something this complicated. It will lead to a support ticket for each new customer.

For now, I think it should be enough to refer to this page: https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util-importPrivateKey.html.

I did not mean to document a complete HSM support in this iteration.
But, I want to recommend at least importing the private key into the HSM (use it as a digital safe).

@doanac WDYT?

maybe. You should consult with support. The problem I see with statement around this are people then asking:

Why AWS instead of $X

How much does it cost?

<insert random question for something we can't predict since we haven't even tried ourselves>

I tried to use vendor neutral sentence, but I think it might be improved like e.g. below:

We recommend storing your Factory Root of Trust in a cloud-based HSM solution of your choice. For example, we verified that the `AWS Cloud HSM <link to landing page>`_ supports `importing EC private keys <link to manual>`_.

Obviously, I need to verify that it really works, before making that bold statement.

I can live with that.

Looks like AWS Cloud HSM advertisement.

wrt customer support: Andy has a point here, we will get inquiries if we don't provide information on this topic. I'm ok with pointing to AWS Cloud HSM. We can always revisit this later if this becomes a pain point.

Rephrased accoring to my suggestion.

source/reference-manual/security/device-gateway.rst

angolini

I cannot finish the review right now. I come back tomorrow from where I left

angolini · 2024-04-04T19:56:12Z

source/reference-manual/security/device-gateway.rst

+LmP devices connect to OTA services via a :ref:`Device Gateway <ref-ota-architecture>` configured with mutual TLS.
+A Factory Public Key Infrastructure (PKI) is a set of Digital Certificates used to establish trust between Factory devices and Device Gateway.
+
+When a new Factory is created, it is configured to use the default "shared" PKI with Certificates owned by Foundries.io™.
+This allows a newcomer to faster engage with the FoundriesFactory®, allowing to streamline your product development.
+


I'm trying new orders for these 4 sentences and my suggestion is:

LmP devices connect to OTA services via a :ref:`Device Gateway <ref-ota-architecture>` configured with mutual TLS. When a new Factory is created, it is configured to use the default "shared" PKI with Certificates owned by Foundries.io™. A Factory Public Key Infrastructure (PKI) is a set of Digital Certificates used to establish trust between Factory devices and Device Gateway. This allows a newcomer to faster engage with the FoundriesFactory®, allowing to streamline your product development.

Why "shared" is in quotes?

I would drop "a newcomer" and would simplify "This allows to faster engage with the....." as it will make it easier for everyone (right? if not, please ignore)

I was also caught by the "shared" in quotes, it seems sketchy

I shuffled sentences/words in a different way, and removed some junk words. Does it look better now?

angolini · 2024-04-04T19:56:59Z

source/reference-manual/security/device-gateway.rst

+When a new Factory is created, it is configured to use the default "shared" PKI with Certificates owned by Foundries.io™.
+This allows a newcomer to faster engage with the FoundriesFactory®, allowing to streamline your product development.
+
+We allow you to set up your own PKI for your Factory — and **encourage** doing that before going to production.


Suggested change

We allow you to set up your own PKI for your Factory — and **encourage** doing that before going to production.

We allow you to set up your own Factory PKI — and **encourage** doing that before going to production.

I remember we talked about "recommendations" on the RM, but I don't know exactly which set of words to use. I will ask @kprosise to comment on the details.

I think this sentence is too loose. I would not say "we allow", and "encourage" is vague. I would say something on the lines:

It is recommended to set up and test a new Factory PKI before going to production.

Maybe highly recommended.

@vkhoroz @doanac I actually think we can forbid connection to DG if a factory-specific PKI is not setup in the production case.

These term, your own Factory PKI or a new Factory PKI maybe just a Factory PKI, or a Factory specific PKI.

@vkhoroz @doanac I actually think we can forbid connection to DG if a factory-specific PKI is not setup in the production case.

We can't. We have customers that are in production without their own PKI.

Also - I kind of prefer "your own PKI". This makes it sound generic like it is and not something we've invented for Factory PKI.

+1 on highly recommend

I actually preserved the original text here... did not want to insult its author as I found it good enough.
As per your recommendation I will truncate amount of imperative buzzwords here to just "recommend".

But I object to using any level-up adjectives: recommendation is a very clear term in ABNF/RFC world, it cannot be higher or lower.
We should use a different word for a higher degree of insistance like should or must; but neither of these words is appropriate here.

source/reference-manual/security/device-gateway.rst

angolini · 2024-04-04T20:15:15Z

source/reference-manual/security/device-gateway.rst

+- Controlling who (which devices) can connect to your Factory device gateway to fetch configuration and software updates.
+- Controlling who (which servers) can deliver configuration and software updates to your Factory devices.


Suggested change

- Controlling who (which devices) can connect to your Factory device gateway to fetch configuration and software updates.

- Controlling who (which servers) can deliver configuration and software updates to your Factory devices.

- Controlling which devices can connect to your Factory Device Gateway to fetch configuration and software updates.

- Controlling which servers can deliver configuration and software updates to your Factory devices.

How "owning your Factory PKI" allows "Controlling who (which servers) can deliver configuration and software updates"? It is the same server/service across all factories - Device Gateway.

It is not necessarily the Foundries.io device gateway - the user is free to set up their own server.
A device gateway here serves only as a medium.

After taking ownership of the Factory PKI a customer is the only entity who can issue the device gateway TLS certificate, and they are free to put any domain into it.
In that way they have full control who delivers updates to their devices.

Before they take ownership of the Factory PKI, it is the Foundries.io who possesses that privilege.

angolini · 2024-04-04T20:19:21Z

source/reference-manual/security/device-gateway.rst

+   The Factory :ref:`Root of Trust <Root-of-Trust>` **can only be set once**; subsequent attempts will fail.
+   Other Factory PKI certificates can be updated at any time; having that you own your Factory Root of Trust.
+
+   `Contact customer support <https://support.foundries.io>` if you need your Factory PKI being reset.


ok, so reset Factory PKI and set up your own Factory PKI are two different things. But both rotate the keys, right? This is only a matter of who is performing the rotation. Maybe a link in the "encourage" sentence (line 12) is missing.

Resetting Factory PKI does not rotate the certificates.
It is like a factory reset - return back to using the shared PKI.

At that point all existing devices will no longer be update to fetch updates, until manual intervention.
We work on rotating the Root of Trust as a separate feature, which is (tentatively) going to be ready in Q4 this year.

this hyperlink is not working, I guess we are missing an _ somewhere

source/reference-manual/security/device-gateway.rst

mike-sul · 2024-04-05T12:01:57Z

source/reference-manual/security/device-gateway.rst

+
+When your Factory devices connect to the Device Gateway, they verify the server identity by validating its TLS Certificate.
+They use the preloaded Factory Root of Trust to perform that validation.
+Once the mutual trust is established, Device Gateway uses its TLS Certificate to setup a session symmetric key.


It sounds like TLS cert is the only thing that is needed/involved in the session key setup.

It is the only one.
A client certificate is involved at a later time during the TLS handshake to for the client authorization after the session was already set up.

mike-sul · 2024-04-05T12:06:03Z

source/reference-manual/security/device-gateway.rst

+The device owns the private key (NIST P-256 by default) and the certificate.
+
+This certificate must be signed by either a :ref:`Local Device CA <local-ca>` or an :ref:`Online Device CA <online-ca>` (see below).
+In particular, the :ref:`lmp-device-register` generates the Device Client Certificate at registration time.


It sounds like an incomplete story after This certificate must be signed by either a :ref:Local Device CA or an :ref:Online Device CA . The lmp-dev-reg` does not generate the cert, it just generates CSR... Probably adding more details and so it includes "signed by/with".

Fixed.

Not sure how much the new version is better... at least it pretends to tell a full story.

mike-sul · 2024-04-05T12:08:17Z

source/reference-manual/security/device-gateway.rst

-In order for ``lmp-device-register`` to work, Foundries.io needs the ability to sign client certificates for devices.
-If enabled, the root of trust will sign an ``online-ca`` certificate that Foundries.io can use to sign client authentication certificates.
+When using the "shared" Factory PKI, this is the only CA used to issue Client Certificates to your Factory devices.
+Once you take ownership of your Factory PKI, you may opt out of using the Online Device CA.


Maybe opt out of using the Online Device CA in favor of Local Device CA?

I disagree. That would make a sentence excessively longer providing marginally more value.

source/reference-manual/security/device-gateway.rst

mike-sul · 2024-04-05T12:16:44Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst


-.. seealso::
-   Documentation on using :ref:`Fioctl® <ug-fioctl>`
+Taking Ownership of Factory PKI Using the API


I think one or more of us should go through these commands and see if they work for him/her.

IIRC I tested these commands before adding to the doc.
Nevertheless, it would be nice is somebody (not me) tries them and provides feedback.

mike-sul · 2024-04-05T12:20:10Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst


-The PKI for Device Gateway and Factory Devices is vital for the secure communication between them.
-It is important to understand exactly what the given command does.
+You can always check your Factory PKI settings using the ``fioctl keys ca show``.


I would structure this introductory paragraph in the form of numbered list. It will kind of outline ordered steps to "Setting Factory PKI through the API". Kind of "to setup factory PKI through the API do 1. <> 2. <> ...

Maybe you are right.
Just ATM I am out of context for this PR and limited in time.
...Preferring to leave that task to the next iteration of improvements.

mike-sul · 2024-04-05T12:21:59Z

I'll follow the guidance on setting a factory PKI through the API to check if it works for me on Monday.

angolini

This is a very complex, extensive text. Sometimes I get confused so I may suggest the wrong thing.

I started taking note of all the terms to try to find out what is a certificate and what is a player, and this is the list of terms (i could note):

Factory PKI
Factory PKI API
Factory RoT
Factory Root CA
Online Device CA
Local Device CA
Factory Local Device CA
Device Gateway
Client Certificate
EST Server TLS Certificate
Device Gateway PKI
server TLS certificate

And I think the players are: Factory, Factory PKI API and Device Gateway.

angolini · 2024-04-05T17:34:59Z

source/reference-manual/security/device-gateway.rst


-In order for ``lmp-device-register`` to work, Foundries.io needs the ability to sign client certificates for devices.
-If enabled, the root of trust will sign an ``online-ca`` certificate that Foundries.io can use to sign client authentication certificates.
+When using the "shared" Factory PKI, this is the only CA used to issue Client Certificates to your Factory devices.


"shared" again. I don't know how to interpret this

maybe "default Factory PKI"

It is both default and shared...
Shared better emphasizes on its essense, as it is exactly the same set of cetificates for all factories.

angolini · 2024-04-05T17:49:31Z

source/reference-manual/security/device-gateway.rst

-Can be used by something like your manufacturing process to sign client certificates for devices—without needing access to Foundries.io.
+An X.509 certificate used as a CA issuing certificates to devices registered via your offline registration process.
+You own the private key (NIST P-256 by default), and share the corresponding certificate with Foundries.io.
+It must be signed by the Root of Trust, so that Foundries.io may verify if a user is entitled to upload a Device CA.


Here "Root of Trust" is alone. In other places, it's "Factory Root of Trust".

Not sure if we need to fix it. I prefer to skip.

angolini · 2024-04-05T18:30:34Z

source/reference-manual/security/device-gateway.rst


-It is also known and referred to as ``offline CA``, since you own its private key and keep it "offline".
+Your factory may only be configured to have one or more Local Device CAs after you took ownership of your Factory PKI.


does that mean I cannot have zero local device CAs?

Added one more sentence to express ability to have zero.

angolini · 2024-04-05T18:38:07Z

source/reference-manual/security/device-gateway.rst

+
+2. Inspect your fleet of already registered devices, and delete those devices which you think are not legitimate.
+   After this point, you can be sure that an attacker can no longer steal your new Intellectual Property (provided by OTA updates).
+   FoundriesFactory advices you to also prepare a separate plan how to deal with already compromised devices.


line 226 can become a note/important/warning

I prefer to keep as is to avoid fancy markup inside a list.

source/user-guide/device-gateway-pki/device-gateway-pki.rst

angolini · 2024-04-05T19:30:12Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst

+3. Optionally Generate Your Local Device CA
+'''''''''''''''''''''''''''''''''''''''''''
+
+Although Foundries.io™ securely stores your Factory Online Device CA; its private key is not owned by you.


if it's not mine, who owns the private key?

I guess Volodya meant ; the private key is owned by you.

I meant what is there - NOT owned by you. This is the essence of the Online Device CA. And this is the primary reason for the below recommendation.

angolini · 2024-04-05T19:31:25Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst

+
+.. important::
+    It is important that the Organization Unit of your Factory Root CA Subject field is set to your Factory name.
+    That information is used by the API to validate that you upload a Root CA for a correct Factory.


Suggested change

That information is used by the API to validate that you upload a Root CA for a correct Factory.

That information is used by the API to validate that you upload a Root CA for the correct Factory.

Not sure, but IMHO in this case a correct is a more correct use: https://textranch.com/c/a-correct-or-the-correct/

source/user-guide/device-gateway-pki/device-gateway-pki.rst

angolini · 2024-04-05T19:38:45Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst


-    openssl ecparam -genkey -name prime256v1 -out devices/offline-device/pkey.pem
+You can replay what the ``lmp-device-register`` and ``factory-registration-reg`` tools do using the following steps using OpenSSL.


replay? mimic? miror?

to try to avoid that tricky word:

Suggested change

You can replay what the ``lmp-device-register`` and ``factory-registration-reg`` tools do using the following steps using OpenSSL.

the following steps use OpenSSL to do the same thing as ``lmp-device-register`` and ``factory-registration-reg``.

Accepted and amended.

vkhoroz · 2024-04-05T20:05:01Z

@doanac @angolini @mike-sul @kprosise thank you so much for your code feedback.

I was intentionally silent during your discussions, because I have too much context on this, so cannot be objective about this text.
Now, that I've got all your inputs, I will try to further improve these pages as per your comments.

angolini · 2024-04-05T20:19:59Z

It looks like we have:
2 safes:

Your Safe

Private Factory Root of Trust

Foundries Safe

Private TLS CRT

I'm not sure how many TLS sessions there is, but I guess it's 2: Factory <-> Device Gateway and Device Gateway <-> each Device?

Then we have 3 players: Factory, Device Gateway, Device

Factory:

Public Factory Root of Trust
Factory PKI
Public TLS for Device Gateway

Device Gateway:

TLS ?
Device Gateway PKI
Online/Offline Device CA?

Device:

something to be identified in the factory (i don't remember the name)
something to context with the Device Gateway

You can see I got lost at some point and cannot actually picture what are the keys and the players. Anyway, I tried to list all moving pieces

mike-sul · 2024-04-08T10:00:54Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst

+1. Call the API to Generate CSRs
+''''''''''''''''''''''''''''''''
+
+You may use `Curl <https://curl.se/>`_ to contact Factory PKI APIs.


Just IMO, the verb contact sounds a bit weird in this context.

Agreed and used verbs play with and call.

mike-sul · 2024-04-08T10:18:54Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst

+        CN = fio-<your-user-uid>
+        OU = <your-factory-name>
+
+    ca.ext:


I think it should be [ext].

Or, it is the file ca.ext, then I would distinguish/separate these two files more clearly.

It is a separate file - that should be evident from indentation and the above sentence referring to configuration fileS.

mike-sul · 2024-04-08T10:34:20Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst

-1. Generates a private key and corresponding Certificate Signing Request (CSR) for Device Gateway (tls-crt);
-2. Generates a private key and corresponding CSR for Online Device CA (online-ca);
-3. Returns a json formatted response to a caller, the response includes:
+    echo "subjectAltName=$(openssl req -text -noout -verify -in tls.csr | grep DNS:)" >> server.ext


The doc doesn't provides details on the tls.csr. Maybe it should be stated explicitly that this file should be generated by extracting the "tls-csr" from the response received from the server on the initial request?

Good catch!
Added a sentence about that in step 1.

source/user-guide/device-gateway-pki/device-gateway-pki.rst

mike-sul · 2024-04-08T10:58:28Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst


-Set offline Device certificate extensions::
+Next, use the following OpenSSL command to generate the private key for your device client certificate::


Maybe just device certificate instead of device client certificate?

I have no strong opinion... the latter just seems more specific to me, as there might be many certificates on the device.

mike-sul · 2024-04-08T11:00:45Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst


-    curl --cacert factory_ca.pem --cert devices/offline-device/client.pem --key devices/offline-device/pkey.pem https://<device-gateway-ID>.ota-lite.foundries.io:8443/repo/1.root.json | jq
+    # Run this command first to see the device gateway host name:
+    openssl x509 -noout -in tls.pem -ext subjectAltName


This command prints two hostnames. Maybe it makes sense to state that *.ota-lite.f.io should be used in the last example, otherwise a user might try the ostree hostname.

The user is only interested in the <device-gateway-ID> but I admit that this sentence does not hint how to obtain it.
I tried to improve - let me know how if it helps.

mike-sul

LGTM, the commands to deal with the API directly work for me, I have just minor comments and suggestions:

No info/example how to register a production device through the API.
No info/example how to register a device through the ota-lite API. The current example is for the auto-registration at DG case.

vanmaegima · 2024-04-18T14:34:11Z

@vkhoroz sorry for the delay on the review, I just noticed this got lost on my inbox during EW
I will try and review this week

vanmaegima · 2024-04-19T17:26:29Z

source/reference-manual/security/device-gateway.rst

+When a new Factory is created, it is configured to use the default "shared" PKI with Certificates owned by Foundries.io™.
+This allows a newcomer to faster engage with the FoundriesFactory®, allowing to streamline your product development.
+
+We allow you to set up your own PKI for your Factory — and **encourage** doing that before going to production.


+1 on highly recommend

vanmaegima · 2024-04-19T17:27:47Z

source/reference-manual/security/device-gateway.rst

+LmP devices connect to OTA services via a :ref:`Device Gateway <ref-ota-architecture>` configured with mutual TLS.
+A Factory Public Key Infrastructure (PKI) is a set of Digital Certificates used to establish trust between Factory devices and Device Gateway.
+
+When a new Factory is created, it is configured to use the default "shared" PKI with Certificates owned by Foundries.io™.
+This allows a newcomer to faster engage with the FoundriesFactory®, allowing to streamline your product development.
+


I was also caught by the "shared" in quotes, it seems sketchy

vanmaegima · 2024-04-19T17:36:01Z

source/reference-manual/security/device-gateway.rst

+    Never lose your Factory Root of Trust, as Foundries.io does not own its copy and is not able to recover it.
+
+    We recommend storing your Factory Root of Trust in a cloud-based HSM solution, like e.g. `AWS Cloud HSM <https://aws.amazon.com/cloudhsm/>`_.
+    That way you get an increased safety of your highly important secret through their redundancy and backup policies.


wrt customer support: Andy has a point here, we will get inquiries if we don't provide information on this topic. I'm ok with pointing to AWS Cloud HSM. We can always revisit this later if this becomes a pain point.

vanmaegima · 2024-04-19T17:39:43Z

source/reference-manual/security/device-gateway.rst


-In order for ``lmp-device-register`` to work, Foundries.io needs the ability to sign client certificates for devices.
-If enabled, the root of trust will sign an ``online-ca`` certificate that Foundries.io can use to sign client authentication certificates.
+When using the "shared" Factory PKI, this is the only CA used to issue Client Certificates to your Factory devices.


maybe "default Factory PKI"

source/user-guide/device-gateway-pki/device-gateway-pki.rst

kprosise · 2024-06-04T07:56:08Z

Once comments/suggestions are resolved, I will give this an in-depth review.

mike-scott · 2024-10-07T18:01:42Z

@vkhoroz I think this PR is still a priority. Do you have time to review the comments and make an update?

kprosise · 2024-10-08T09:13:24Z

Once all technical content is verified, I can help with cleanup. There is also a lot of good suggestions already, which should be applied.

vkhoroz · 2024-10-09T13:13:50Z

@mike-scott @kprosise Jumping on it for today and tomorrow.

vkhoroz · 2024-10-12T17:45:18Z

@kprosise @doanac @dagriego @vanmaegima @mike-sul
I tried to incorporate your suggestions to the maximum of my current capacity.

Please, let me know how can it be improved further.

doanac · 2024-10-12T18:29:03Z

Docs for 92e0b00 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2777/docs/artifacts/html/index.html

doanac · 2024-10-12T18:49:16Z

Docs for 30c6e00 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2778/docs/artifacts/html/index.html

Signed-off-by: Volodymyr Khoroz <volodymyr.khoroz@foundries.io>

doanac · 2024-10-12T18:51:43Z

Docs for ec00631 are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2779/docs/artifacts/html/index.html

kprosise · 2024-10-15T08:07:51Z

@vkhoroz reviewing your comments and changes, I am comfortable going ahead and merging this if there is no other feedback. If it sounds good to you, I will give it until Thursday before merging.

kprosise

lgtm

vanmaegima

minor comments on cross references and hyperlinks not working, otherwise lgtm

vanmaegima · 2024-10-15T19:26:18Z

source/reference-manual/security/device-gateway.rst

+   The Factory :ref:`Root of Trust <Root-of-Trust>` **can only be set once**; subsequent attempts will fail.
+   Other Factory PKI certificates can be updated at any time; having that you own your Factory Root of Trust.
+
+   `Contact customer support <https://support.foundries.io>` if you need your Factory PKI being reset.


this hyperlink is not working, I guess we are missing an _ somewhere

vanmaegima · 2024-10-15T19:28:48Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst

+- Generates a server-side crypto-key for the ref:`tls-crt` and returns a Certificate Signing Request (CSR) for it.
+- Optionally generates a server-side crypto-key for the ref:`online-ca` and returns a CSR for it.
+- Optionally generates a server-side crypto-key for the ref:`est-tls-crt` and returns a CSR for it.


should these ref: be referencing somewhere in the doc?
maybe this should be ``

ref: -> :ref: they are just missing colons in front. Working on a patch for this commit right now.

vanmaegima · 2024-10-15T19:34:37Z

source/user-guide/device-gateway-pki/device-gateway-pki.rst

-This guide covers Public Key Infrastructure (PKI) Settings.
-In particular, the low-level details of what happens behind the scenes when running the ``fioctl keys ca`` commands.
-It also provides instructions to create, sign, and use an *offline* (aka *local*) device certificate.
+   `Contact customer support <https://support.foundries.io>` if you need your Factory PKI being reset.


same here for the hyperlink

vanmaegima · 2024-10-15T19:39:45Z

source/reference-manual/security/device-gateway.rst

+   FoundriesFactory advices you to also prepare a separate plan how to deal with already compromised devices.
+
+3. Rotate client certificates on your devices which have a client certificate issued by a Device CA you are revoking.
+   You may use Foundries.io hosted ref:`ref-cert-rotation` service, or use your own certificate rotation workflow.


ref is not working here

kprosise · 2024-10-16T07:48:33Z

source/reference-manual/security/device-gateway.rst

+   The Factory :ref:`Root of Trust <Root-of-Trust>` **can only be set once**; subsequent attempts will fail.
+   Other Factory PKI certificates can be updated at any time; having that you own your Factory Root of Trust.
+
+   `Contact customer support <https://support.foundries.io>` if you need your Factory PKI being reset.


Suggested change

`Contact customer support <https://support.foundries.io>` if you need your Factory PKI being reset.

`Contact customer support <https://support.foundries.io>`_ if you need your Factory PKI being reset.

kprosise · 2024-10-17T09:50:45Z

I am going to go ahead and merge, and I will follow up with a PR to fix issues with hyperlinks.

vkhoroz self-assigned this Apr 4, 2024

vkhoroz requested review from kprosise, doanac, angolini, vanmaegima, mike-sul and caiotpereira April 4, 2024 13:32

doanac reviewed Apr 4, 2024

View reviewed changes

angolini approved these changes Apr 4, 2024

View reviewed changes

mike-sul reviewed Apr 5, 2024

View reviewed changes

source/reference-manual/security/device-gateway.rst Outdated Show resolved Hide resolved

mike-sul reviewed Apr 5, 2024

View reviewed changes

source/reference-manual/security/device-gateway.rst Outdated Show resolved Hide resolved

mike-sul reviewed Apr 5, 2024

View reviewed changes

angolini approved these changes Apr 5, 2024

View reviewed changes

mike-sul reviewed Apr 8, 2024

View reviewed changes

source/user-guide/device-gateway-pki/device-gateway-pki.rst Show resolved Hide resolved

mike-sul reviewed Apr 8, 2024

View reviewed changes

source/user-guide/device-gateway-pki/device-gateway-pki.rst Outdated Show resolved Hide resolved

mike-sul reviewed Apr 8, 2024

View reviewed changes

mike-sul approved these changes Apr 8, 2024

View reviewed changes

vanmaegima reviewed Apr 19, 2024

View reviewed changes

vkhoroz force-pushed the vkhoroz-pki-updates branch 2 times, most recently from 34f3cf2 to fb6790a Compare October 12, 2024 17:44

vkhoroz force-pushed the vkhoroz-pki-updates branch from fb6790a to 92e0b00 Compare October 12, 2024 18:25

vkhoroz force-pushed the vkhoroz-pki-updates branch from 92e0b00 to 30c6e00 Compare October 12, 2024 18:45

Update Factory PKI docs according to recent changes

ec00631

Signed-off-by: Volodymyr Khoroz <volodymyr.khoroz@foundries.io>

vkhoroz force-pushed the vkhoroz-pki-updates branch from 30c6e00 to ec00631 Compare October 12, 2024 18:49

kprosise approved these changes Oct 15, 2024

View reviewed changes

vanmaegima approved these changes Oct 15, 2024

View reviewed changes

kprosise reviewed Oct 16, 2024

View reviewed changes

kprosise merged commit 29eafcd into foundriesio:main Oct 17, 2024
2 of 3 checks passed

	You own the private key (NIST P-256 by default), and share the corresponding certificate with Foundries.io.
	You own the private key (NIST P-256 by default), and share the corresponding public certificate with Foundries.io.

	We allow you to set up your own PKI for your Factory — and encourage doing that before going to production.
	We allow you to set up your own Factory PKI — and encourage doing that before going to production.

		- Controlling who (which devices) can connect to your Factory device gateway to fetch configuration and software updates.
		- Controlling who (which servers) can deliver configuration and software updates to your Factory devices.


		It is also known and referred to as ``offline CA``, since you own its private key and keep it "offline".
		Your factory may only be configured to have one or more Local Device CAs after you took ownership of your Factory PKI.

	That information is used by the API to validate that you upload a Root CA for a correct Factory.
	That information is used by the API to validate that you upload a Root CA for the correct Factory.


		openssl ecparam -genkey -name prime256v1 -out devices/offline-device/pkey.pem
		You can replay what the ``lmp-device-register`` and ``factory-registration-reg`` tools do using the following steps using OpenSSL.

	You can replay what the ``lmp-device-register`` and ``factory-registration-reg`` tools do using the following steps using OpenSSL.
	the following steps use OpenSSL to do the same thing as ``lmp-device-register`` and ``factory-registration-reg``.


		Set offline Device certificate extensions::
		Next, use the following OpenSSL command to generate the private key for your device client certificate::

	`Contact customer support <https://support.foundries.io>` if you need your Factory PKI being reset.
	`Contact customer support <https://support.foundries.io>`_ if you need your Factory PKI being reset.

Update Factory PKI docs according to recent changes #699

Update Factory PKI docs according to recent changes #699

Conversation

vkhoroz commented Apr 4, 2024 • edited Loading

PR Template and Checklist

Readiness

Overview

Checklist

Comments

vkhoroz commented Apr 4, 2024

vkhoroz commented Apr 4, 2024 • edited Loading

kprosise commented Apr 4, 2024

doanac left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vkhoroz Apr 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vkhoroz Apr 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

angolini left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mike-sul commented Apr 5, 2024

angolini left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vkhoroz commented Apr 5, 2024

angolini commented Apr 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vkhoroz commented Apr 4, 2024 •

edited

Loading

vkhoroz commented Apr 4, 2024 •

edited

Loading

vkhoroz Apr 4, 2024 •

edited

Loading

vkhoroz Apr 4, 2024 •

edited

Loading