From dfba1108b862d9ae29f3d3fe837671b4b8dbdf3e Mon Sep 17 00:00:00 2001 From: Jon Oster Date: Fri, 24 Jan 2020 16:56:30 +0100 Subject: [PATCH 01/14] Update display version Signed-off-by: Jon Oster --- docs/ota-client-guide/antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ota-client-guide/antora.yml b/docs/ota-client-guide/antora.yml index 5901a1ad7a..ffd4f9128d 100644 --- a/docs/ota-client-guide/antora.yml +++ b/docs/ota-client-guide/antora.yml @@ -1,6 +1,6 @@ name: ota-client title: OTA Connect Developer Guide version: latest -display_version: 2019.11 (latest) +display_version: 2020.1 (latest) nav: - modules/ROOT/nav.adoc From f7903bdc17b461c89206ce94cf5277d3162b06ca Mon Sep 17 00:00:00 2001 From: amma Date: Fri, 13 Dec 2019 09:36:42 +0100 Subject: [PATCH 02/14] Revision of Provisioning page Signed-off-by: amma --- docs/ota-client-guide/modules/ROOT/nav.adoc | 3 +- .../pages/client-provisioning-methods.adoc | 65 ++++++++----------- 2 files changed, 29 insertions(+), 39 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/nav.adoc b/docs/ota-client-guide/modules/ROOT/nav.adoc index 2dcc67d6e6..522230775c 100644 --- a/docs/ota-client-guide/modules/ROOT/nav.adoc +++ b/docs/ota-client-guide/modules/ROOT/nav.adoc @@ -25,9 +25,10 @@ ifndef::env-github[:pageroot:] // --- * xref:{pageroot}security.adoc[Security] ** xref:{pageroot}pki.adoc[Key management] +** xref:{pageroot}client-provisioning-methods.adoc[Device provisioning] ** xref:{pageroot}uptane.adoc[The Uptane security specification] // future iteration: * xref:{pageroot}prod-intro[Testing and production environments] -* xref:{pageroot}client-provisioning-methods.adoc[Device provisioning] + .Evaluate OTA Connect * xref:{pageroot}intro-evaluate.adoc[Evaluating OTA Connect] diff --git a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc index ef1170d069..d6df0e7d6c 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc @@ -14,63 +14,52 @@ endif::[] :icons: font :toc: macro -Before devices can receive updates, each device needs to have a unique identity and a certificate. The provisioning process ensures that a signed certificate is associated with each device. This process is crucial for securing communication between devices and the OTA Connect server. -OTA Connect supports two provisioning methods. These methods determine the components that will play the role of the "issuer" and the "verifier" in your infrastructure. The "issuer" is the server that signs and issues your device certificates. The "verifier" is the server that verifies the authenticity of device certificates. -We refer these two methods as "provisioning with shared credentials" and "provisioning with device credentials". +For secure communication, a vehicle needs to have an X.509 certificate and it needs to trust the device gateway’s X.509 certificate. (Each account has its own unique device gateway, and that certificate is included in the credentials.zip and baked into the image as a pinned CA when you bitbake.) The device gateway trusts a vehicle’s X.509 certificate if and only if that certificate is signed by what we call the fleet root certificate authority (CA). Every device, regardless of how it is initially provisioned, ends up with its own unique X.509 certificate signed by the fleet root CA. Whenever the device interacts with the OTA Connect server, the device gateway authenticates and identifies it by its X.509 certificate. +The provisioning process ensures that a signed certificate is associated with each device. This process is crucial for securing communication between devices and the OTA Connect server. +OTA Connect supports two provisioning methods. We refer to these two methods as "provisioning with shared credentials" and "provisioning with device credentials". -* *Provisioning with shared credentials* -+ -This type of provisioning is great for testing because the OTA Connect server plays the role of both the "issuer" and "verifier" when creating device certificates. You can try out OTA Connect without involving the rest of your infrastructure. However, it's not secure enough for a production scenario. -+ -* *Provisioning with device credentials* -+ -This is the provisioning method that you should use in production. In this scenario, the OTA Connect server doesn't issue any credentials to devices; it simply inspects device certificates that come preinstalled. The OTA Connect server only plays the role of "verifier" and the "issuer" role is handled by your fleet certificate authority. +Note that in both cases, the server must have access to the fleet root CA for your fleet. The fleet root CA is used to sign identity metadata of thclconnected devices. -.How the server roles change depending on which method you choose: -[caption="Figure 1: "] -image::img::prov-diff-infra.png[] +Let's take a closer look at how each method works. -Note that in both cases, the server that plays "issuer" role, must have access to the private key and the root certificate for your fleet. The root certificate and private key are used to sign identity metadata and to verify the identity of connected devices. +. *Provisioning with shared credentials* -Let's take a close look at how each method works. +This type of provisioning is great for testing because the OTA Connect server manages the certificates and keys of the device. You can try out OTA Connect without involving the rest of your infrastructure. However, this method is not secure enough for a production scenario. -== Provisioning with shared credentials +In shared credential provisioning, the OTA Connect server creates the fleet root CA for you, and stores the private key for the CA in a Vault. You include a provisioning key for the device in the image — the “shared credential”. -This method is called "provisioning with shared credentials" because you install a temporary provisioning key that is shared by all devices. -With this method, perform the following major steps: +In this method, the following steps occur: -* You download a temporary provisioning key from the OTA Connect server and install it on a base software image. -* You then flash your base software image to your devices. -* Once each device boots up, it uses the shared provisioning key to request a permanent device certificate from the OTA Connect server. -* The OTA Connect server verifies the provisioning key, issues the device with an X.509 certificate which is then downloaded to the device. -* The device then uses this certificate for all future transactions. +* You should download your initial provisioning key from your OTA Connect account, and bake it into the image for the device. +* The first time the device comes online, it connects to the device gateway and says, “Hi, I’m a new device, and I don’t have a TLS certificate yet. Here’s my provisioning key.” +* Then, our crypto service generates a new keypair and X.509 certificate for the device, signs that certificate with the private fleet root CA in the Vault instance, and sends the whole bundle to the vehicle. +* Then it deletes the vehicle’s private key. -This method is fine for provisioning devices quickly but if a malicious actor steals your provisioning key, there's no way to prevent unauthorized devices from provisioning. You'd have to blacklist the provisioning key for all devices and issue a new one. +This entire transaction is secured with TLS, using the pinned device gateway certificate provisioned in the image. -== Provisioning with device credentials + +[arabic, start=2] +. *Provisioning with device credentials* If you're using OTA Connect in production, you should provision with device credentials. -In this scenario, the OTA Connect server doesn't issue any credentials to devices. You need to preinstall the device certificates yourself. -How you get the certificates on to your devices is your decision. Your chosen method can depend on many variables such as the storage method on the device, whether you have connectivity at your factory, and whether you choose an internal or third party root of trust for your certificates. -For example, you might have a deployment process where your build system requests a certificate from your CA while a software image is being built. The device certificate is then installed on the image just before it is flashed to the target device. -Once a device boots up, it connects to the OTA Connect server and provides the pre-installed device certificate to verify the device identity. The OTA Connect server then verifies that the certificate came from your CA. -With this method, it is extremely difficult for an unauthorized device to join your fleet. +In this method there is no shared credential. Instead the following steps occur: + +* You provide us with your own fleet root CA’s certificate (but NOT the private key). +* Then, you make sure that each device acquires, in some out-of-band process, an X.509 certificate signed by your fleet root CA. In an ideal world, you would generate a keypair and a self-signed X.509 certificate inside an HSM on the device (so that there’s never any private key material outside of the HSM), then submit a CSR for that self-signed device certificate using your own existing PKI (e.g. via PKCS#10), and an authentication method of your choosing. (In an automotive OEM context, for example, that might be a private server inside the factory infrastructure, using the physical location and an airgapped network as ways to authenticate the request’s validity.) +* Once the device has its signed certificate, it can register with the OTA Connect server: we simply verify that your fleet root CA has signed the vehicle certificate, and use the CNI on the vehicle certificate to identify it. If a device with that name already exists, it’s a normal update transaction; If not, we register it as a new vehicle. +Note that nowhere in this process have we had to use a shared credential, nor has any private key material existed outside of the vehicle (for vehicle keys), or your own PKI (for the fleet root CA). We have also used mutual TLS for transport security right from the beginning. This is why we describe this process as the more secure option. -The following diagram summarizes the differences in how devices are provisioned between the two methods. -.How the server roles change depending on which method you choose: -[caption="Figure 2: "] -image::img::prov-diff-devices.png[] +With "shared credential" provisioning, devices are identified by the provisioning key. The role of the OTA server is to generate a keypair and an X.509 certificate, and sign off with the fleet root CA. +With "device credential" provisioning, you decide how devices are identified. You provide the OTA server with only your fleet root CA and ensure your devices already have an X.509 certificate signed by your fleet root CA. -With "shared credential" provisioning, devices identified by the provisioning key and the device ID. The role of "issuer" is played by the OTA Connect server, which expects a provisioning key. -With "device credential" provisioning, you decide how devices are identified. You could generate and preinstall certificate signing request (CSR) files which provide your Certificate Authority (CA) with all the necessary identification details. == Setting up the OTA Connect Server for Provisioning -If you want to use "shared credential" provisioning, we'll generate a fleet root certificate and private key for you and store them on the OTA Connect server. We take the security of these keys and certificates extremely seriously: following industry best practices, they are kept in a Vault instance and only taken out when you request them. -If you want to use "device credential" provisioning, you'll need to provide us with your own fleet root certificate so that the OTA Connect server can verify devices. +If you want to use "shared credential" provisioning, we'll generate a fleet root CA and keypair for you and store them on the OTA Connect server. We take the security of these keys and certificates extremely seriously: following industry best practices, they are kept in a Vault instance and only taken out when you request them. +If you want to use "device credential" provisioning, you'll need to provide us with your own fleet root CA so that the OTA Connect server can verify devices. Of course, you can use both methods, but in that case, we recommend that you maintain separate user accounts: * one account for testing with "shared credential" provisioning From 688dac7eb4971372df2031707f87837898128678 Mon Sep 17 00:00:00 2001 From: amma Date: Fri, 13 Dec 2019 13:04:07 +0100 Subject: [PATCH 03/14] Minor edit on revision of Provisioning page Signed-off-by: amma --- .../modules/ROOT/pages/client-provisioning-methods.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc index d6df0e7d6c..78f6372d26 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc @@ -18,7 +18,7 @@ For secure communication, a vehicle needs to have an X.509 certificate and it ne The provisioning process ensures that a signed certificate is associated with each device. This process is crucial for securing communication between devices and the OTA Connect server. OTA Connect supports two provisioning methods. We refer to these two methods as "provisioning with shared credentials" and "provisioning with device credentials". -Note that in both cases, the server must have access to the fleet root CA for your fleet. The fleet root CA is used to sign identity metadata of thclconnected devices. +Note that in both cases, the server must have access to the fleet root CA for your fleet. The fleet root CA is used to sign the certificate of the connected devices. Let's take a closer look at how each method works. From c8ad03c37feeca5b81c9e8345a1a9c6e6f874baa Mon Sep 17 00:00:00 2001 From: amma Date: Thu, 9 Jan 2020 11:11:34 +0100 Subject: [PATCH 04/14] Introduction added to provisionig page Signed-off-by: amma --- .../ROOT/pages/client-provisioning-methods.adoc | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc index 78f6372d26..aa54a8ec9d 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc @@ -14,16 +14,20 @@ endif::[] :icons: font :toc: macro + +Before devices can receive updates, each device needs to have a unique identity and a certificate. The provisioning process ensures that a signed certificate is associated with each device. This process is crucial for securing communication between devices and the OTA Connect server. + +OTA Connect supports two provisioning methods. These methods determine the components that will issue and verify the certificate in your infrastructure. We refer to these two methods as "*provisioning with shared credentials*" and "*provisioning with device credentials*". The end result of these two provisioning methods is the same, as they both provide a device with a signed certificate that can be used for communication. + + For secure communication, a vehicle needs to have an X.509 certificate and it needs to trust the device gateway’s X.509 certificate. (Each account has its own unique device gateway, and that certificate is included in the credentials.zip and baked into the image as a pinned CA when you bitbake.) The device gateway trusts a vehicle’s X.509 certificate if and only if that certificate is signed by what we call the fleet root certificate authority (CA). Every device, regardless of how it is initially provisioned, ends up with its own unique X.509 certificate signed by the fleet root CA. Whenever the device interacts with the OTA Connect server, the device gateway authenticates and identifies it by its X.509 certificate. -The provisioning process ensures that a signed certificate is associated with each device. This process is crucial for securing communication between devices and the OTA Connect server. -OTA Connect supports two provisioning methods. We refer to these two methods as "provisioning with shared credentials" and "provisioning with device credentials". Note that in both cases, the server must have access to the fleet root CA for your fleet. The fleet root CA is used to sign the certificate of the connected devices. Let's take a closer look at how each method works. -. *Provisioning with shared credentials* +=== Provisioning with shared credentials This type of provisioning is great for testing because the OTA Connect server manages the certificates and keys of the device. You can try out OTA Connect without involving the rest of your infrastructure. However, this method is not secure enough for a production scenario. @@ -34,13 +38,13 @@ In this method, the following steps occur: * You should download your initial provisioning key from your OTA Connect account, and bake it into the image for the device. * The first time the device comes online, it connects to the device gateway and says, “Hi, I’m a new device, and I don’t have a TLS certificate yet. Here’s my provisioning key.” * Then, our crypto service generates a new keypair and X.509 certificate for the device, signs that certificate with the private fleet root CA in the Vault instance, and sends the whole bundle to the vehicle. -* Then it deletes the vehicle’s private key. +* Lastly, it deletes the vehicle’s private key. This entire transaction is secured with TLS, using the pinned device gateway certificate provisioned in the image. -[arabic, start=2] -. *Provisioning with device credentials* + +=== Provisioning with device credentials If you're using OTA Connect in production, you should provision with device credentials. In this method there is no shared credential. Instead the following steps occur: @@ -59,6 +63,7 @@ With "device credential" provisioning, you decide how devices are identified. Yo == Setting up the OTA Connect Server for Provisioning If you want to use "shared credential" provisioning, we'll generate a fleet root CA and keypair for you and store them on the OTA Connect server. We take the security of these keys and certificates extremely seriously: following industry best practices, they are kept in a Vault instance and only taken out when you request them. + If you want to use "device credential" provisioning, you'll need to provide us with your own fleet root CA so that the OTA Connect server can verify devices. Of course, you can use both methods, but in that case, we recommend that you maintain separate user accounts: From 4e7a3531683a928464d44d77070c40ee3983fbba Mon Sep 17 00:00:00 2001 From: Amma Boateng <58598320+ammaboateng@users.noreply.github.com> Date: Thu, 16 Jan 2020 10:17:32 +0100 Subject: [PATCH 05/14] Minor punctuation edits on provisioning page Co-Authored-By: Patrick Vacek Signed-off-by: Amma Boateng <58598320+ammaboateng@users.noreply.github.com> Signed-off-by: Mike Sul --- .../pages/client-provisioning-methods.adoc | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc index aa54a8ec9d..39572e63ec 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc @@ -20,43 +20,44 @@ Before devices can receive updates, each device needs to have a unique identity OTA Connect supports two provisioning methods. These methods determine the components that will issue and verify the certificate in your infrastructure. We refer to these two methods as "*provisioning with shared credentials*" and "*provisioning with device credentials*". The end result of these two provisioning methods is the same, as they both provide a device with a signed certificate that can be used for communication. -For secure communication, a vehicle needs to have an X.509 certificate and it needs to trust the device gateway’s X.509 certificate. (Each account has its own unique device gateway, and that certificate is included in the credentials.zip and baked into the image as a pinned CA when you bitbake.) The device gateway trusts a vehicle’s X.509 certificate if and only if that certificate is signed by what we call the fleet root certificate authority (CA). Every device, regardless of how it is initially provisioned, ends up with its own unique X.509 certificate signed by the fleet root CA. Whenever the device interacts with the OTA Connect server, the device gateway authenticates and identifies it by its X.509 certificate. +For secure communication, a vehicle needs to have an X.509 certificate and it needs to trust the device gateway’s X.509 certificate. Each account has its own unique certificate on the device gateway, and that certificate is included in the `credentials.zip` and baked into the image as a pinned certificate authority (CA) when you bitbake. The device gateway trusts a vehicle’s X.509 certificate if and only if that certificate is signed by what we call the fleet root CA. Every device, regardless of how it is initially provisioned, ends up with its own unique X.509 certificate signed by the fleet root CA. Whenever the device interacts with the OTA Connect server, the device gateway authenticates and identifies it by its X.509 certificate. Note that in both cases, the server must have access to the fleet root CA for your fleet. The fleet root CA is used to sign the certificate of the connected devices. Let's take a closer look at how each method works. -=== Provisioning with shared credentials +== Provisioning with shared credentials -This type of provisioning is great for testing because the OTA Connect server manages the certificates and keys of the device. You can try out OTA Connect without involving the rest of your infrastructure. However, this method is not secure enough for a production scenario. +This type of provisioning is great for testing because the OTA Connect server generates the certificates and keys of the device. You can try out OTA Connect without involving the rest of your infrastructure. However, this method may not be secure enough for a production scenario. In shared credential provisioning, the OTA Connect server creates the fleet root CA for you, and stores the private key for the CA in a Vault. You include a provisioning key for the device in the image — the “shared credential”. In this method, the following steps occur: -* You should download your initial provisioning key from your OTA Connect account, and bake it into the image for the device. -* The first time the device comes online, it connects to the device gateway and says, “Hi, I’m a new device, and I don’t have a TLS certificate yet. Here’s my provisioning key.” -* Then, our crypto service generates a new keypair and X.509 certificate for the device, signs that certificate with the private fleet root CA in the Vault instance, and sends the whole bundle to the vehicle. -* Lastly, it deletes the vehicle’s private key. +. You should download your initial provisioning key from your OTA Connect account, and bake it into the image for the device. +. The first time the device comes online, it connects to the device gateway and says, “Hi, I’m a new device, and I don’t have a TLS certificate yet. Here’s my provisioning key.” +. Then, our crypto service generates a new keypair and X.509 certificate for the device, signs that certificate with the private fleet root CA in the Vault instance, and sends the whole bundle to the vehicle. +. Lastly, the crypto service deletes the vehicle’s private key and the device stores its new keypair and certificate. This entire transaction is secured with TLS, using the pinned device gateway certificate provisioned in the image. -=== Provisioning with device credentials +== Provisioning with device credentials If you're using OTA Connect in production, you should provision with device credentials. In this method there is no shared credential. Instead the following steps occur: -* You provide us with your own fleet root CA’s certificate (but NOT the private key). -* Then, you make sure that each device acquires, in some out-of-band process, an X.509 certificate signed by your fleet root CA. In an ideal world, you would generate a keypair and a self-signed X.509 certificate inside an HSM on the device (so that there’s never any private key material outside of the HSM), then submit a CSR for that self-signed device certificate using your own existing PKI (e.g. via PKCS#10), and an authentication method of your choosing. (In an automotive OEM context, for example, that might be a private server inside the factory infrastructure, using the physical location and an airgapped network as ways to authenticate the request’s validity.) -* Once the device has its signed certificate, it can register with the OTA Connect server: we simply verify that your fleet root CA has signed the vehicle certificate, and use the CNI on the vehicle certificate to identify it. If a device with that name already exists, it’s a normal update transaction; If not, we register it as a new vehicle. +. You provide us with your own fleet root CA’s certificate (but NOT the private key). +. Then, you make sure that each device acquires, in some out-of-band process, an X.509 certificate signed by your fleet root CA. In an ideal world, you would generate a keypair and a self-signed X.509 certificate inside an HSM on the device (so that there’s never any private key material outside of the HSM), then submit a CSR for that self-signed device certificate using your own existing PKI (e.g. via PKCS#10) and an authentication method of your choosing. In an automotive OEM context, for example, that might be a private server inside the factory infrastructure, using the physical location and an airgapped network as ways to authenticate the request’s validity. +. Once the device has its signed certificate, it can register with the OTA Connect server. We simply verify that your fleet root CA has signed the vehicle certificate, and use the CNI on the vehicle certificate to identify it. If a device with that name already exists, it's a normal update transaction; if not, we register it as a new vehicle. Note that nowhere in this process have we had to use a shared credential, nor has any private key material existed outside of the vehicle (for vehicle keys), or your own PKI (for the fleet root CA). We have also used mutual TLS for transport security right from the beginning. This is why we describe this process as the more secure option. -With "shared credential" provisioning, devices are identified by the provisioning key. The role of the OTA server is to generate a keypair and an X.509 certificate, and sign off with the fleet root CA. +With "shared credential" provisioning, devices are identified by the provisioning key. It is the role of the OTA server to generate a keypair and an X.509 certificate, and sign off with the fleet root CA. + With "device credential" provisioning, you decide how devices are identified. You provide the OTA server with only your fleet root CA and ensure your devices already have an X.509 certificate signed by your fleet root CA. From 1ef838dcba994c602e5f5c55d7848b3f4e0b3902 Mon Sep 17 00:00:00 2001 From: amma Date: Fri, 17 Jan 2020 13:53:39 +0100 Subject: [PATCH 06/14] Addition of provisioning images Signed-off-by: amma --- .../modules/ROOT/pages/client-provisioning-methods.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc index 39572e63ec..556443bc97 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc @@ -42,6 +42,9 @@ In this method, the following steps occur: This entire transaction is secured with TLS, using the pinned device gateway certificate provisioned in the image. +.Summary of Shared credentials provisioning +[caption="Figure 1: "] +image::shared-cred-provisioning.png[1280, 500] == Provisioning with device credentials @@ -60,6 +63,9 @@ With "shared credential" provisioning, devices are identified by the provisionin With "device credential" provisioning, you decide how devices are identified. You provide the OTA server with only your fleet root CA and ensure your devices already have an X.509 certificate signed by your fleet root CA. +.Summary of Device credentials provisioning +[caption="Figure 2: "] +image::device-cred-provisioning.png[1280,500] == Setting up the OTA Connect Server for Provisioning From 2ffcb934c0b812712a64762866ec4020c7d114fc Mon Sep 17 00:00:00 2001 From: Jon Oster Date: Thu, 23 Jan 2020 16:12:01 +0100 Subject: [PATCH 07/14] DOCS: Some final edits to provisioning guide Signed-off-by: Jon Oster --- .../_partials/why-different-prov-methods.adoc | 8 ++- .../pages/client-provisioning-methods.adoc | 60 +++++++++++-------- .../enable-device-cred-provisioning.adoc | 2 +- 3 files changed, 42 insertions(+), 28 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/_partials/why-different-prov-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/_partials/why-different-prov-methods.adoc index c0ec6dcc77..7bd72c7660 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/_partials/why-different-prov-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/_partials/why-different-prov-methods.adoc @@ -1,6 +1,8 @@ -If you followed the xref:getstarted::get-started.adoc[Get Started Guide], you used a provisioning key that was shared by all devices. In this scenario, the OTA Connect server generates the device credentials for you. This method is fine if you're just evaluating OTA Connect and want to get started quickly. If you want to do some serious testing and eventually move to production, you'll need a switch to a more secure provisioning method. +If you followed the xref:getstarted::get-started.adoc[Get Started Guide], you used a provisioning key that was shared by all devices. In this scenario, the OTA Connect server generates the device credentials for you. This method is fine if you're just evaluating OTA Connect and want to get started quickly. If you want to do some serious testing and eventually move to production, you'll need a switch to a more secure provisioning method. -In this case, you shouldn't use the OTA Connect server to generate your device credentials. If you generate *and* validate credentials with the same server, you're taking a big risk. Generation and validation should always be done by separate entities. +In this case, you shouldn't use the OTA Connect server to generate your device credentials. If you generate *and* validate credentials with the same server, you're taking a big risk. Generation and validation should always be done by separate entities. Otherwise, if an attacker were able to infiltrate the OTA Connect server, they would be able to provision their own devices. -Instead, you should use your own infrastructure to generate device credentials outside of OTA Connect. We call this method "provisioning with device credentials". +Instead, you should use your own infrastructure to generate device credentials outside of OTA Connect. We call this method "provisioning with device credentials". + +TIP: For a more detailed conceptual overview of the difference between the two types of provisioning, read our xref:client-provisioning-methods.adoc[guide to device provisioning]. diff --git a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc index 556443bc97..74509e2442 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc @@ -14,62 +14,74 @@ endif::[] :icons: font :toc: macro +== What is device provisioning? -Before devices can receive updates, each device needs to have a unique identity and a certificate. The provisioning process ensures that a signed certificate is associated with each device. This process is crucial for securing communication between devices and the OTA Connect server. +OTA Connect uses mutual TLS for transport security and device authentication. This means that: -OTA Connect supports two provisioning methods. These methods determine the components that will issue and verify the certificate in your infrastructure. We refer to these two methods as "*provisioning with shared credentials*" and "*provisioning with device credentials*". The end result of these two provisioning methods is the same, as they both provide a device with a signed certificate that can be used for communication. +* every device needs to have its own X.509 certificate, +* every device needs to have a way to trust the X.509 certificate of the OTA Connect server's device gateway, and +* the OTA Connect server needs to have a way to decide whether it trusts each vehicle's X.509 certificate. +The vehicle knows it can trust the gateway because each OTA Connect account gets a unique device gateway URL, with its own unique X.509 certificate. We then include that certificate in the `credentials.zip` you download, and it gets baked into the image as a pinned certificate authority (CA) when you bitbake. -For secure communication, a vehicle needs to have an X.509 certificate and it needs to trust the device gateway’s X.509 certificate. Each account has its own unique certificate on the device gateway, and that certificate is included in the `credentials.zip` and baked into the image as a pinned certificate authority (CA) when you bitbake. The device gateway trusts a vehicle’s X.509 certificate if and only if that certificate is signed by what we call the fleet root CA. Every device, regardless of how it is initially provisioned, ends up with its own unique X.509 certificate signed by the fleet root CA. Whenever the device interacts with the OTA Connect server, the device gateway authenticates and identifies it by its X.509 certificate. +The device gateway decides whether to allow a device to connect based on the device's X.509 certificate. Every OTA Connect account has one or more *Fleet Root CAs* which are responsible for signing device certificates. When a device connects, your device gateway checks whether its certificate is signed by a trusted Fleet Root CA, and if not, rejects the connection. -Note that in both cases, the server must have access to the fleet root CA for your fleet. The fleet root CA is used to sign the certificate of the connected devices. +*Device provisioning*, therefore, is simply the process of providing a device with: -Let's take a closer look at how each method works. +* an X.509 certificate +** that is unique to the vehicle +*** and is signed by a Fleet Root CA that your OTA Connect account trusts + +== How to provision devices + +OTA Connect supports two provisioning methods: "*provisioning with shared credentials*" and "*provisioning with device credentials*". No matter which method you choose, you'll end up in the same place: each of your devices will have its own signed certificate, and will use that certificate to identify itself and establish a secure communication channel with the server (via mutual TLS). + +The difference between the two methods is in how exactly that certificate gets to the vehicle, and who controls the Fleet Root CA. Let's take a closer look at how each method works. == Provisioning with shared credentials -This type of provisioning is great for testing because the OTA Connect server generates the certificates and keys of the device. You can try out OTA Connect without involving the rest of your infrastructure. However, this method may not be secure enough for a production scenario. +This type of provisioning is the default, and is great to start with, because the OTA Connect server does everything for you: it generates a Fleet Root CA for your account, and it generates a new vehicle certificate every time a new device comes online. This allows you to try out OTA Connect without involving the rest of your infrastructure. However, this method may not be secure enough for a production scenario. -In shared credential provisioning, the OTA Connect server creates the fleet root CA for you, and stores the private key for the CA in a Vault. You include a provisioning key for the device in the image — the “shared credential”. +In shared credential provisioning, the OTA Connect server creates the fleet root CA for you, and stores the private key for the CA in a https://www.vaultproject.io/[Vault] instance. The server also generates a credential for you that can be shared amongst all the devices in your fleet. That credential--also known as a provisioning key--is included in your `credentials.zip`, and is baked into the generic image that you flash on all your devices. In this method, the following steps occur: -. You should download your initial provisioning key from your OTA Connect account, and bake it into the image for the device. -. The first time the device comes online, it connects to the device gateway and says, “Hi, I’m a new device, and I don’t have a TLS certificate yet. Here’s my provisioning key.” -. Then, our crypto service generates a new keypair and X.509 certificate for the device, signs that certificate with the private fleet root CA in the Vault instance, and sends the whole bundle to the vehicle. -. Lastly, the crypto service deletes the vehicle’s private key and the device stores its new keypair and certificate. +. You download your `credentials.zip` with the provisioning key inside. +. You bitbake an image with the default provisioning method configured, providing bitbake with your `credentials.zip`. +. You flash that image on as many devices as you wish. +. The first time each device comes online, it connects to a special endpoint on the device gateway and says, “Hi, I’m a new device, and I don’t have a TLS certificate yet. Here’s my provisioning key.” +. Our crypto service generates a new keypair and X.509 certificate for the device, signs that certificate with the private Fleet Root CA in the Vault instance, and sends the whole bundle to the vehicle. +. The crypto service deletes the vehicle’s private key and the device stores its new keypair and certificate. This entire transaction is secured with TLS, using the pinned device gateway certificate provisioned in the image. -.Summary of Shared credentials provisioning +.Summary of Shared credential provisioning [caption="Figure 1: "] image::shared-cred-provisioning.png[1280, 500] == Provisioning with device credentials -If you're using OTA Connect in production, you should provision with device credentials. -In this method there is no shared credential. Instead the following steps occur: +We usually recommend this provisioning method if you have high cybersecurity compliance needs, and especially if you have devices with a hardware security module. In this method there is no shared credential. Instead, the following steps occur: -. You provide us with your own fleet root CA’s certificate (but NOT the private key). -. Then, you make sure that each device acquires, in some out-of-band process, an X.509 certificate signed by your fleet root CA. In an ideal world, you would generate a keypair and a self-signed X.509 certificate inside an HSM on the device (so that there’s never any private key material outside of the HSM), then submit a CSR for that self-signed device certificate using your own existing PKI (e.g. via PKCS#10) and an authentication method of your choosing. In an automotive OEM context, for example, that might be a private server inside the factory infrastructure, using the physical location and an airgapped network as ways to authenticate the request’s validity. -. Once the device has its signed certificate, it can register with the OTA Connect server. We simply verify that your fleet root CA has signed the vehicle certificate, and use the CNI on the vehicle certificate to identify it. If a device with that name already exists, it's a normal update transaction; if not, we register it as a new vehicle. +. You provide us with your own Fleet Root CA’s certificate (but NOT the private key). +. Then, you make sure that each device acquires, in some out-of-band process, an X.509 certificate signed by your fleet root CA. ++ +For maximum security, you would generate a keypair and a self-signed X.509 certificate inside an HSM on the device (so that there’s never any private key material outside of the HSM), then submit a PKCS#10 certificate signing request (CSR) to an appropriate service inside your own PKI, using an authentication method appropriate to your security needs. In an automotive OEM context, for example, that might be a private server inside the factory infrastructure, using the physical location and an airgapped network as ways to authenticate the CSR’s validity. +. Once the device has its signed certificate, it can already establish a mutual TLS connection with OTA Connect server. Any time a device that's not already in the system connects with a valid certificate, we add it to your fleet, using the CNI on the vehicle certificate as the device ID. Note that nowhere in this process have we had to use a shared credential, nor has any private key material existed outside of the vehicle (for vehicle keys), or your own PKI (for the fleet root CA). We have also used mutual TLS for transport security right from the beginning. This is why we describe this process as the more secure option. +TIP: For a more practical overview, read our xref:enable-device-cred-provisioning.adoc[step-by-step guide to setting up device credential provisioning]. -With "shared credential" provisioning, devices are identified by the provisioning key. It is the role of the OTA server to generate a keypair and an X.509 certificate, and sign off with the fleet root CA. - -With "device credential" provisioning, you decide how devices are identified. You provide the OTA server with only your fleet root CA and ensure your devices already have an X.509 certificate signed by your fleet root CA. - -.Summary of Device credentials provisioning +.Summary of Device credential provisioning [caption="Figure 2: "] image::device-cred-provisioning.png[1280,500] == Setting up the OTA Connect Server for Provisioning -If you want to use "shared credential" provisioning, we'll generate a fleet root CA and keypair for you and store them on the OTA Connect server. We take the security of these keys and certificates extremely seriously: following industry best practices, they are kept in a Vault instance and only taken out when you request them. +If you want to use "shared credential" provisioning, you don't have to do anything at all. When your account was created, we already generated a fleet root CA and keypair for you, and stored them on the OTA Connect server. We take the security of these keys extremely seriously: following industry best practices, they are kept in a Vault instance and only taken out when you request them. If you want to use "device credential" provisioning, you'll need to provide us with your own fleet root CA so that the OTA Connect server can verify devices. Of course, you can use both methods, but in that case, we recommend that you maintain separate user accounts: @@ -77,5 +89,5 @@ Of course, you can use both methods, but in that case, we recommend that you mai * one account for testing with "shared credential" provisioning * one account for production with "device credential" provisioning -Migrating devices from a test account to a production account is an extremely complex process and should be avoided. Instead, we recommend that you test with devices that will not go into production or devices that can be completely reset for production. +Migrating devices from a test account to a production account is an extremely complex process and should be avoided. Instead, we recommend that you test with devices that will not go into production or devices that can be completely wiped and reset once they are ready to deploy. Once you are ready for production, you should use your production account, your own fleet root certificate, and production devices that have their device certificates preinstalled. diff --git a/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provisioning.adoc b/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provisioning.adoc index 4d0b0ce4c3..87e8620c9f 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provisioning.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provisioning.adoc @@ -76,7 +76,7 @@ scp -P 2222 autoprov.url root@localhost:/var/sota/import/gateway.url + [NOTE] ==== -You might remember that `credentials.zip` contains a provisioning key for shared-credential provisioning. In this case we just need the `autoprov.url` file inside `credentials.zip`. This file contains the URL of your device gateway which is specific to your account. +You might remember that `credentials.zip` normally contains a provisioning key for shared-credential provisioning. In this case, we just need the `autoprov.url` file inside `credentials.zip`. This file contains the URL of your device gateway, which is specific to your account. ==== . Copy the device credentials and device gateway root CA certificate to the device. + From 6a039a02cb339d91832115bc1605d22382cfbf5b Mon Sep 17 00:00:00 2001 From: Jon Oster Date: Thu, 23 Jan 2020 16:52:09 +0100 Subject: [PATCH 08/14] Consistent capitalization for Fleet Root CA Signed-off-by: Jon Oster --- .../ROOT/pages/client-provisioning-methods.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc index 74509e2442..d441f78dfc 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc @@ -43,7 +43,7 @@ The difference between the two methods is in how exactly that certificate gets t This type of provisioning is the default, and is great to start with, because the OTA Connect server does everything for you: it generates a Fleet Root CA for your account, and it generates a new vehicle certificate every time a new device comes online. This allows you to try out OTA Connect without involving the rest of your infrastructure. However, this method may not be secure enough for a production scenario. -In shared credential provisioning, the OTA Connect server creates the fleet root CA for you, and stores the private key for the CA in a https://www.vaultproject.io/[Vault] instance. The server also generates a credential for you that can be shared amongst all the devices in your fleet. That credential--also known as a provisioning key--is included in your `credentials.zip`, and is baked into the generic image that you flash on all your devices. +In shared credential provisioning, the OTA Connect server creates the Fleet Root CA for you, and stores the private key for the CA in a https://www.vaultproject.io/[Vault] instance. The server also generates a credential for you that can be shared amongst all the devices in your fleet. That credential--also known as a provisioning key--is included in your `credentials.zip`, and is baked into the generic image that you flash on all your devices. In this method, the following steps occur: @@ -66,12 +66,12 @@ image::shared-cred-provisioning.png[1280, 500] We usually recommend this provisioning method if you have high cybersecurity compliance needs, and especially if you have devices with a hardware security module. In this method there is no shared credential. Instead, the following steps occur: . You provide us with your own Fleet Root CA’s certificate (but NOT the private key). -. Then, you make sure that each device acquires, in some out-of-band process, an X.509 certificate signed by your fleet root CA. +. Then, you make sure that each device acquires, in some out-of-band process, an X.509 certificate signed by your Fleet Root CA. + For maximum security, you would generate a keypair and a self-signed X.509 certificate inside an HSM on the device (so that there’s never any private key material outside of the HSM), then submit a PKCS#10 certificate signing request (CSR) to an appropriate service inside your own PKI, using an authentication method appropriate to your security needs. In an automotive OEM context, for example, that might be a private server inside the factory infrastructure, using the physical location and an airgapped network as ways to authenticate the CSR’s validity. . Once the device has its signed certificate, it can already establish a mutual TLS connection with OTA Connect server. Any time a device that's not already in the system connects with a valid certificate, we add it to your fleet, using the CNI on the vehicle certificate as the device ID. -Note that nowhere in this process have we had to use a shared credential, nor has any private key material existed outside of the vehicle (for vehicle keys), or your own PKI (for the fleet root CA). We have also used mutual TLS for transport security right from the beginning. This is why we describe this process as the more secure option. +Note that nowhere in this process have we had to use a shared credential, nor has any private key material existed outside of the vehicle (for vehicle keys), or your own PKI (for the Fleet Root CA). We have also used mutual TLS for transport security right from the beginning. This is why we describe this process as the more secure option. TIP: For a more practical overview, read our xref:enable-device-cred-provisioning.adoc[step-by-step guide to setting up device credential provisioning]. @@ -81,9 +81,9 @@ image::device-cred-provisioning.png[1280,500] == Setting up the OTA Connect Server for Provisioning -If you want to use "shared credential" provisioning, you don't have to do anything at all. When your account was created, we already generated a fleet root CA and keypair for you, and stored them on the OTA Connect server. We take the security of these keys extremely seriously: following industry best practices, they are kept in a Vault instance and only taken out when you request them. +If you want to use "shared credential" provisioning, you don't have to do anything at all. When your account was created, we already generated a Fleet Root CA and keypair for you, and stored them on the OTA Connect server. We take the security of these keys extremely seriously: following industry best practices, they are kept in a Vault instance and only taken out when you request them. -If you want to use "device credential" provisioning, you'll need to provide us with your own fleet root CA so that the OTA Connect server can verify devices. +If you want to use "device credential" provisioning, you'll need to provide us with your own Fleet Root CA so that the OTA Connect server can verify devices. Of course, you can use both methods, but in that case, we recommend that you maintain separate user accounts: * one account for testing with "shared credential" provisioning From 54aed097ccba9484725b580c690819fbd078e38e Mon Sep 17 00:00:00 2001 From: Jon Oster Date: Thu, 23 Jan 2020 17:02:48 +0100 Subject: [PATCH 09/14] Accuracy improvements to key management page Signed-off-by: Jon Oster --- .../modules/ROOT/pages/pki.adoc | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/pki.adoc b/docs/ota-client-guide/modules/ROOT/pages/pki.adoc index 5f5d944cac..541633421e 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/pki.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/pki.adoc @@ -8,30 +8,27 @@ We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname} endif::[] -Once you move to production, we recommend that you manage these keys offline in your own PKI rather than having all keys managed on the OTA Connect server. +OTA Connect uses public key cryptography to protect sensitive data. Once you move to production, we recommend that you manage these keys offline rather than having all keys managed on the OTA Connect server. -OTA Connect uses pairs of public and private keys to protect sensitive data. Normally, you use a PKI (Public Key Infrastructure) to manage these keys. +== Risks keeping your keys on the OTA Connect server -== Risks of using OTA Connect as your PKI +When you first sign up for an account, OTA Connect generates all of the keys you need and securely stores them, so you don't have to worry about key management to get started. -By default, OTA Connect server plays the role of a PKI so you don't have to think about key management. This is useful if you don't yet have your own PKI, but not so secure. +However, this means that OTA Connect account password is the only thing standing between an attacker and your devices. If your password was guessed or stolen, the attacker would be install whatever software they wanted on any of devices OTA Connect manages. If your device happens to be a vehicle, such a breach could have very dangerous consequences. -If an attacker were able to take over your OTA Connect account, they would be able to provision their own devices and send malicious updates to your devices. If your device happens to be a vehicle, such a breach could have very dangerous consequences. - -This is why we recommend that you use your own PKI in production. +This is why we recommend xref:rotating-signing-keys.adoc[rotating your software signing keys offline] and xref:client-provisioning-methods.adoc[choosing an appropriately secure provisioning method]. == Key Types -If you follow our security recommendations, you'll need to manage several different keys. +If you follow our highest security recommendations, you'll need to manage several different keys. .Key Types [width="100%",cols="2,2,4",options="header"] |==================== -| Key Name | Purpose | Description -| Fleet Root | Device Identity | This key is used to sign your fleet root certificate. The root certificate certifies the identity of your fleet and is used to sign device certificates. The OTA Connect server can then validate device certificates to ensure that a connecting device is part of your fleet. +| Key Name | Purpose | Description +| Fleet Root | Device Identity | The private key of your Fleet Root CA. This is used to sign the individual device certificates for your fleet of devices. The OTA Connect server can then validate device certificates to ensure that a connecting device is part of your fleet. See xref:client-provisioning-methods.adoc[Device Provisioning Methods] for more details. -If you obtain a root certificate from an external certificate authority such as DigiCert, you don't have to worry about managing this key. The certificate authority takes are of this for you. | Uptane Root | Software Integrity | This key is used to sign the "root" metadata file for your software repository. This file contains information about all the roles that can sign software metadata. For more information on how to take these keys offline, see the topic "xref:rotating-signing-keys.adoc[Manage keys for software metadata]". | Uptane Targets | Software Integrity | This key is used to sign the "targets" metadata file for software updates. This file contains information about all the valid software files in your software repository. For more information on how to take these keys offline, see the topic "xref:rotating-signing-keys.adoc[Manage keys for software metadata]". |==================== From 5592165c046c21b72feea68aadbe3efe666a2957 Mon Sep 17 00:00:00 2001 From: Jon Oster Date: Thu, 23 Jan 2020 17:34:11 +0100 Subject: [PATCH 10/14] Correct bad PKI information Signed-off-by: Jon Oster --- .../pages/client-provisioning-methods.adoc | 2 +- .../modules/ROOT/pages/deploy-checklist.adoc | 30 +++++++++---------- .../enable-device-cred-provisioning.adoc | 2 +- .../ROOT/pages/generate-devicecert.adoc | 4 +-- .../ROOT/pages/generate-selfsigned-root.adoc | 4 +-- .../modules/ROOT/pages/provide-root-cert.adoc | 7 ++--- 6 files changed, 24 insertions(+), 25 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc index d441f78dfc..f2b2688f9f 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc @@ -90,4 +90,4 @@ Of course, you can use both methods, but in that case, we recommend that you mai * one account for production with "device credential" provisioning Migrating devices from a test account to a production account is an extremely complex process and should be avoided. Instead, we recommend that you test with devices that will not go into production or devices that can be completely wiped and reset once they are ready to deploy. -Once you are ready for production, you should use your production account, your own fleet root certificate, and production devices that have their device certificates preinstalled. +Once you are ready for production, you should use your production account, your own Fleet Root certificate, and production devices that have their device certificates preinstalled. diff --git a/docs/ota-client-guide/modules/ROOT/pages/deploy-checklist.adoc b/docs/ota-client-guide/modules/ROOT/pages/deploy-checklist.adoc index 6f33bfbbb7..9b8f4c5c83 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/deploy-checklist.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/deploy-checklist.adoc @@ -8,43 +8,43 @@ We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname} endif::[] -OTA Connect is designed to integrate easily into development workflows: you build your image, push it, set auto-updates for some of your test-bench devices, and so on. But once you're ready to move from testing into production, you will likely want to do a few things differently. +OTA Connect is designed to integrate easily into development workflows: you build your image, push it, set auto-updates for some of your test-bench devices, and so on. But once you're ready to move from testing into production, you will likely want to do a few things differently. Here is a checklist for all the tasks you should consider when moving to production: [cols="2,5a,2a",options="header"] |==================== | Task | Summary | Documentation -|**Register the root certificate for your fleet ** | +|**Register the root certificate for your fleet ** | * If you followed our recommendations, you should have accounts for development, testing and production. -** If you also followed our recommendation to use device-credential povisioning, you need to register your fleet root certificate with your production account +** If you also followed our recommendation to use device-credential provisioning, you need to register your Fleet Root certificate with your production account -* You might have already registered a self-signed root certificate with your test account. +* You might have already registered a self-signed root certificate with your test account. + -However, regardless of the type of certficate that you use, you'll need to register a new certificate with your *production* account. | +However, regardless of the type of certficate that you use, you'll need to register a new certificate with your *production* account. | * xref:client-provisioning-methods.adoc[Device provisioning methods] * xref:provide-root-cert.adoc[Register the Root Certificate for your Fleet] -|**Generate and install final device certs** | -* Once you have your final fleet root certificate, you can use it to generate and sign device certificates. +|**Generate, sign, and install production device certs** | +* Once you have your production Fleet Root CA, you can use it to sign device certificates. + -You can then automate the process of installing device certificates on your devices. +You can then automate the process of either generating the device certificates on your devices and getting them signed via PKCS#10 CSR, or of generating and signing the keys and certs externally, and then installing them into a secure place on each device. * We can’t tell you exactly how to automate this process, but you can use the commands from our documentation as a guideline. -| +| * xref:generate-devicecert.adoc[Generate a device certificate] * xref:enable-device-cred-provisioning.adoc[Enable device-credential provisioning and install device certificates] -|**Rotate production keys** | -* In line with our security concept, We recommend that you sign disk images with secure, offline keys. +|**Rotate production keys** | +* In line with our security concept, we recommend that you sign software version with secure, offline keys. * Even if you've done this already for with a test account, you need to do it again with a `credentials.zip` from your production account. * You should keep these keys on a secure storage medium such as a link:https://www.yubico.com/[YubiKey]. You would only plug in your YubiKey when you need to sign metadata on your local computer.| xref:rotating-signing-keys.adoc[Manage keys for software metadata] -|**Transfer disk images to your production repository** | +|**Transfer disk images to your production repository** | * When you're ready to deploy your software to production, you'll need to move all approved disk images from the software repository in your testing account to the one in your production account. | xref:cross-deploy-images.adoc[Transfer software to another repository] -|**Create production-ready client configuration** | +|**Create production-ready client configuration** | * You'll need to update the configuration for aktualizr or libaktualizr. + -Settings that are convenient for testing, such as small polling invervals, are not suitable for production and should be changed. | xref:recommended-clientconfig.adoc[Recommended client configurations] -|==================== \ No newline at end of file +Settings that are convenient for testing, such as small polling invervals, are not suitable for production and should be changed. | xref:recommended-clientconfig.adoc[Recommended client configurations] +|==================== diff --git a/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provisioning.adoc b/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provisioning.adoc index 87e8620c9f..e779bc905b 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provisioning.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provisioning.adoc @@ -18,7 +18,7 @@ How you get the certificate on the device is up to you: * You could have your HSM generate a private key and certificate directly on the device. + -You woud then sign the certificate with your fleet root key. +You would then use your Fleet Root CA to sign the device's certificate, for example using a PKCS#10 request. + ** We don't have documentation on how to do this, since the method is different for each HSM model. * You can also generate the device certificates and private keys on your development computer and copy them over to the device. diff --git a/docs/ota-client-guide/modules/ROOT/pages/generate-devicecert.adoc b/docs/ota-client-guide/modules/ROOT/pages/generate-devicecert.adoc index 4e1ad3ff73..6e42bab5e6 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/generate-devicecert.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/generate-devicecert.adoc @@ -8,7 +8,7 @@ We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname} endif::[] -Once you have your final fleet root certificate, you can use it to generate and sign device certificates. You can then automate the process of installing device certificates on your devices. +Once you have your final Fleet Root CA, you can use it to sign device certificates. You can then automate the process of installing device certificates, or generate the keys and certificate on the device and sign the cert via PKCS#10 CSR. We can't tell you exactly how to automate this process, but heres a recap of the steps involved. @@ -31,7 +31,7 @@ end::createdevicedir[] ==== You might want to update the line `export DEVICE_UUID=` and update it to reflect your own schema for generating device IDs. Currently this command generates a random ID. ==== -. Generate a device certificate and public key, and sign it with your fleet root certificate. +. Generate a device certificate and public key, and sign it using your Fleet Root CA. + As a reference, here is the command to generate and sign a device certificate with a self-signed root certificate. + diff --git a/docs/ota-client-guide/modules/ROOT/pages/generate-selfsigned-root.adoc b/docs/ota-client-guide/modules/ROOT/pages/generate-selfsigned-root.adoc index afe9964506..edb993f0a9 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/generate-selfsigned-root.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/generate-selfsigned-root.adoc @@ -8,9 +8,9 @@ We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname} endif::[] -When you move to production, you'll need to register your fleet root certificate with OTA Connect server. This certificate needs to be signed by a trusted Certificate Authority (CA). +When you move to production, you'll need to register your Fleet Root certificate with OTA Connect server. -If you don't yet have your own CA certificate for signing device certificates, you can generate a self-signed certificate for testing. +If you don't yet have your own CA for signing device certificates, you can generate a self-signed certificate for testing. // tag::install-root-ca[] diff --git a/docs/ota-client-guide/modules/ROOT/pages/provide-root-cert.adoc b/docs/ota-client-guide/modules/ROOT/pages/provide-root-cert.adoc index c95cf6d34e..1f2cb7cf2b 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/provide-root-cert.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/provide-root-cert.adoc @@ -10,14 +10,13 @@ endif::[] //MC: This is a copy of the topic "provide-testroot-cert.adoc" but intended for the "prod" use case. Need to use more includes to reduce redundancy -Once you are ready to move to production, you need to have your final fleet root certificate registered with your production account. Ideally, your fleet root certificate should come from an external certificate authority (CA) who can take care of safeguarding your private key. +Once you are ready to move to production, you need to have your final Fleet Root certificate registered with your production account. -During testing, you might have followed our procedure to generate a self-signed root certificate and had it registered with your test account. We don't recommend using a self-signed certificate for production because it makes you more vulnerable to security breaches. Nevertheless, if you'd prefer to stick with a self-signed certificate, you'll need to generate another one and have it registered with your production account. -* To register your fleet root certificate with HERE OTA Connect, send it to link:mailto:otaconnect.support@here.com[otaconnect.support@here.com]. +* To register your Fleet Root certificate with HERE OTA Connect, send it to link:mailto:otaconnect.support@here.com[otaconnect.support@here.com]. If you followed our recommendations, you should have one OTA Connect account for testing and another for production. Make sure that you specify that this certificate is for your *production* account. * While you wait for confirmation from the OTA Connect support team, you can already set up your xref:generate-devicecert.adoc[device certificate generation]. -* Once you've received confirmation that the fleet root certificate has been registered, you can xref:enable-device-cred-provisioning.adoc[enable device-credential provisioning and install the certificates] on your devices. \ No newline at end of file +* Once you've received confirmation that the Fleet Root certificate has been registered, you can xref:enable-device-cred-provisioning.adoc[enable device-credential provisioning and install the certificates] on your devices. From 0a0265ed984bf0a23be81f141c67d8beab4a7e86 Mon Sep 17 00:00:00 2001 From: Jon Oster Date: Fri, 24 Jan 2020 18:27:03 +0100 Subject: [PATCH 11/14] Add provisioning images, fix image syntax Signed-off-by: Jon Oster --- .../modules/ROOT/pages/client-provisioning-methods.adoc | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc index f2b2688f9f..92eedfaf4e 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc @@ -57,9 +57,7 @@ In this method, the following steps occur: This entire transaction is secured with TLS, using the pinned device gateway certificate provisioned in the image. .Summary of Shared credential provisioning -[caption="Figure 1: "] -image::shared-cred-provisioning.png[1280, 500] - +image::img::shared-cred-provisioning.png[width=100%] == Provisioning with device credentials @@ -76,8 +74,7 @@ Note that nowhere in this process have we had to use a shared credential, nor ha TIP: For a more practical overview, read our xref:enable-device-cred-provisioning.adoc[step-by-step guide to setting up device credential provisioning]. .Summary of Device credential provisioning -[caption="Figure 2: "] -image::device-cred-provisioning.png[1280,500] +image::img::device-cred-provisioning.png[width=100%] == Setting up the OTA Connect Server for Provisioning From 7d5e15144edff0ad23356c1c71d3eac0b80bb5fe Mon Sep 17 00:00:00 2001 From: Jon Oster Date: Fri, 24 Jan 2020 18:43:30 +0100 Subject: [PATCH 12/14] Minor fixes to explanation of why to use different provisioning methods Signed-off-by: Jon Oster --- .../ROOT/pages/_partials/why-different-prov-methods.adoc | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/_partials/why-different-prov-methods.adoc b/docs/ota-client-guide/modules/ROOT/pages/_partials/why-different-prov-methods.adoc index 7bd72c7660..721e78b7f8 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/_partials/why-different-prov-methods.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/_partials/why-different-prov-methods.adoc @@ -1,8 +1,5 @@ -If you followed the xref:getstarted::get-started.adoc[Get Started Guide], you used a provisioning key that was shared by all devices. In this scenario, the OTA Connect server generates the device credentials for you. This method is fine if you're just evaluating OTA Connect and want to get started quickly. If you want to do some serious testing and eventually move to production, you'll need a switch to a more secure provisioning method. +If you followed the xref:getstarted::get-started.adoc[Get Started Guide], you used a provisioning key that was shared by all devices. In this scenario, the OTA Connect server generates the device credentials for you. This method is fine if you're just evaluating OTA Connect and want to get started quickly. If you want to do some serious testing and eventually move to production, you'll probably want to switch to a more secure provisioning method. -In this case, you shouldn't use the OTA Connect server to generate your device credentials. If you generate *and* validate credentials with the same server, you're taking a big risk. Generation and validation should always be done by separate entities. -Otherwise, if an attacker were able to infiltrate the OTA Connect server, they would be able to provision their own devices. - -Instead, you should use your own infrastructure to generate device credentials outside of OTA Connect. We call this method "provisioning with device credentials". +Instead of having OTA Connect generate device certificates for you, you can use your own infrastructure to generate and sign device credentials. We call this method "provisioning with device credentials". TIP: For a more detailed conceptual overview of the difference between the two types of provisioning, read our xref:client-provisioning-methods.adoc[guide to device provisioning]. From c885c947d5d3c403d729dfdfa9d29e70147df7d3 Mon Sep 17 00:00:00 2001 From: Jon Oster Date: Fri, 24 Jan 2020 19:22:51 +0100 Subject: [PATCH 13/14] Remove unused pages These pages are no longer used. They aren't in the navigation, but they were discoverable using the search function. Signed-off-by: Jon Oster --- .../pages/device-cred-prov-teststeps.adoc | 31 ---- .../pages/enable-device-cred-provtest.adoc | 134 ------------------ .../ROOT/pages/generatetest-devicecert.adoc | 70 --------- .../modules/ROOT/pages/intro-prod.adoc | 44 ------ .../ROOT/pages/provide-testroot-cert.adoc | 21 --- .../pages/secure-software-updates-test.adoc | 19 --- .../update-your-client-configuration.adoc | 44 ------ 7 files changed, 363 deletions(-) delete mode 100644 docs/ota-client-guide/modules/ROOT/pages/device-cred-prov-teststeps.adoc delete mode 100644 docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provtest.adoc delete mode 100644 docs/ota-client-guide/modules/ROOT/pages/generatetest-devicecert.adoc delete mode 100644 docs/ota-client-guide/modules/ROOT/pages/intro-prod.adoc delete mode 100644 docs/ota-client-guide/modules/ROOT/pages/provide-testroot-cert.adoc delete mode 100644 docs/ota-client-guide/modules/ROOT/pages/secure-software-updates-test.adoc delete mode 100644 docs/ota-client-guide/modules/ROOT/pages/update-your-client-configuration.adoc diff --git a/docs/ota-client-guide/modules/ROOT/pages/device-cred-prov-teststeps.adoc b/docs/ota-client-guide/modules/ROOT/pages/device-cred-prov-teststeps.adoc deleted file mode 100644 index aa70bd5518..0000000000 --- a/docs/ota-client-guide/modules/ROOT/pages/device-cred-prov-teststeps.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= Text Device-credential Provisioning -ifdef::env-github[] - -[NOTE] -==== -We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. -==== -endif::[] - - -Although shared-credential provisioning is useful for evaluating OTA Connect, we don't recommend that you use it in production. - -If you want to test provisioning properly, you should provision devices with their own certificates. In a production scenario, you'll need to automate the process of provisioning devices with their own certificates, but for testing you can provision devices manually. - -The following major steps show you how to provision test devices with device certificates: - -* xref:generate-selfsigned-root.adoc[Generate a test root certificate]. -+ -If you don't yet have your fleet's root certificate, we show you how to generate one yourself for testing. - -* xref:provide-testroot-cert.adoc[Provide us with your test root certificate] -+ -We'll need to register your test root certificate with a test account, so that the OTA Connect server can verify your test device certificates. - -* xref:generatetest-devicecert.adoc[Generate and sign a test device certificate] -+ -Once you've generated a test root certificate, you can use it to sign a test device certificate. - -* xref:enable-device-cred-provtest.adoc[Enable and install the device certificate] -+ -We show you how to enable device-credential provisioning and install a device certificate on a test device. Once you've provisioned test devices with certificates, they can authenticate with the OTA Connect server. \ No newline at end of file diff --git a/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provtest.adoc b/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provtest.adoc deleted file mode 100644 index b9d22968ca..0000000000 --- a/docs/ota-client-guide/modules/ROOT/pages/enable-device-cred-provtest.adoc +++ /dev/null @@ -1,134 +0,0 @@ -= Enable device-credential provisioning and install device certificates -ifdef::env-github[] - -[NOTE] -==== -We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. -==== -endif::[] - - -//MC: This is a copy of the topic "enable-device-cred-provisioning.adoc" but intended for the "test" use case. Need to use more includes to reduce redundancy. - -If you've followed our recommendation to use device-credential provisioning, you'll need to test how it works in your environment. You start by building disk images that are configured to use device-credential provisioning. - -After you have flashed those images to devices, you boot the image and install the device certicate for each device. You can install the certificate to the device's fileystem or use an HSM. - -== Enable and install _without_ an HSM - -You don't need an HSM to provision with device credentials, but we recommend that you use one. If you want to do without an HSM for now, use this procedure. - -To enable device-credential provisioning and install device certificates _without_ an HSM, follow these steps: :: - -. Add the following lines to your `conf/local.conf`: -+ ----- -SOTA_CLIENT_PROV = "aktualizr-device-prov" -SOTA_DEPLOY_CREDENTIALS = "0" -SOTA_PACKED_CREDENTIALS = "/path/to/your/credentials.zip" -IMAGE_INSTALL_append = " dropbear " ----- -+ -[NOTE] -==== -The line `IMAGE_INSTALL_append = " dropbear "` ensures that an ssh server is installed on the image. You'll need to ssh into the device to copy the certificates to the device's filesystem. -==== -. Build a standard image using bitbake. -. Boot the image. -. Run the following commands to tell the device what server URL to connect to: -+ -[source,sh,subs="attributes"] ----- -unzip credentials.zip autoprov.url -scp -P 2222 autoprov.url root@localhost:/var/sota/import/gateway.url ----- -+ -[NOTE] -==== -You might remember that `credentials.zip` contains a provisioning key shared-credential provisioning. In this case we just need the `autoprov.url` file inside `credentials.zip`. This file contains the URL of your device gateway which is specific to your account. -==== -. Copy the device credentials and device gateway root CA certificate to the device. -+ -[source,sh] ----- -export device_dir=path/to/device/dir -scp -P 2222 -pr ${device_dir} root@localhost:/var/sota/import ----- -+ -[NOTE] -==== -Replace `path/to/device/dir` with the device directory that you noted when xref:generatetest-devicecert.adoc[generating the device certificate]. -==== -+ -. _(Optional)_ When the copy operation has completed, ssh into your device and check the aktualizr log output with the following `systemd` command: -+ -`journalctl -f -u aktualizr` -+ -Once the certificates have copied, the following chain of events should occur: -+ -.. The server authenticates the client device by verifying that the client's certificate was signed by the root CA private key that was uploaded in step 2. -.. The client device authenticates the server by verifying that the server's certificate was signed by the server's internal root CA private key. -.. The device is provisioned and appears online in the web UI. - - -== Enable and install _with_ an HSM - -As described in the xref:index.adoc[introduction], it's a good idea to use a Hardware Security Model (HSM) to hold potentially sensitive device credentials. - -The following procedure describes how to use QEMU and link:https://www.opendnssec.org/softhsm/[SoftHSM] to simulate a device with an HSM. - -However, the procedure for your HSM will probably be different. We've provided these instructions as a basic guide to how this provisioning method works but you'll need to make further changes on your own. For example, you'll probably need to adapt your BSP so that aktualizr can access the keys from your HSM. - -To enable device-credential provisioning and install device certificates _with_ an HSM, follow these steps: :: - -. Add the following lines to your `conf/local.conf`: -+ ----- -SOTA_CLIENT_FEATURES = "hsm" -SOTA_CLIENT_PROV = "aktualizr-device-prov-hsm" -SOTA_DEPLOY_CREDENTIALS = "0" -IMAGE_INSTALL_append = " softhsm-testtoken dropbear " ----- -+ -[NOTE] -==== -The line `IMAGE_INSTALL_append = " softhsm-testtoken dropbear "` ensures that softhsm and an ssh server are installed on the image. You'll need to ssh into the device to copy the certificates to the hsm. -==== -. Build a standard image using bitbake. -. Boot the image. -. Run the following commands to tell the device what server URL to connect to: -+ -[source,sh,subs="attributes"] ----- -unzip credentials.zip autoprov.url -scp -P 2222 autoprov.url root@localhost:/var/sota/import/gateway.url ----- -+ -[NOTE] -==== -You might remember that `credentials.zip` contains a provisioning key shared-credential provisioning. In this case we just need the `autoprov.url` file inside `credentials.zip`. This file contains the URL of your device gateway which is specific to your account. -==== -. Copy the device credentials and device gateway root CA certificate to the device's HSM. -+ -[source,sh] ----- -export device_dir=path/to/device/dir -scp -P 2222 -pr ${device_dir} root@localhost:/var/sota/import ----- -+ -[NOTE] -==== -Replace `path/to/device/dir` with the device directory that you noted when xref:generatetest-devicecert.adoc[generating the device certificate]. - -For the QEMU simulated HSM, replace `path/to/device/dir` with the credentials directory of the relevant device. -==== -+ -. _(Optional)_ When the copy operation has completed, ssh into your device and check the aktualizr log output with the following `systemd` command: -+ -`journalctl -f -u aktualizr` -+ -Once the certificates have copied, the following chain of events should occur: -+ -.. The server authenticates the client device by verifying that the client's certificate was signed by the root CA private key that was uploaded in step 2. -.. The client device authenticates the server by verifying that the server's certificate was signed by the server's internal root CA private key. -.. The device is provisioned and appears online in the web UI. diff --git a/docs/ota-client-guide/modules/ROOT/pages/generatetest-devicecert.adoc b/docs/ota-client-guide/modules/ROOT/pages/generatetest-devicecert.adoc deleted file mode 100644 index 84a439eab0..0000000000 --- a/docs/ota-client-guide/modules/ROOT/pages/generatetest-devicecert.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= Generate a test device certificate -ifdef::env-github[] - -[NOTE] -==== -We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. -==== -endif::[] - - -// MC: This is a slightly altered copy of "generate-devicecert.doc" with wording that explains the process from the perspective of testing with a self-signed root cert. - -Once you have created a self-signed root certificate, you can use it to generate and sign device certificates. You then install these certificates on your test devices. - -*Generate a test device certificate, follow these steps* - -. Generate a UUID for the device, and make a directory for it: -+ -[source,bash] ----- -export SERVER_NAME=myservername -export DEVICES_DIR = DEVICES_DIR="./${SERVER_NAME}/devices" CWD="${PWD}" -export DEVICE_UUID=$(uuidgen | tr "[:upper:]" "[:lower:]") -export device_id=${DEVICE_ID:-${DEVICE_UUID}} device_dir="${DEVICES_DIR}/${DEVICE_UUID}" -mkdir -p "${device_dir}" ----- -+ -[NOTE] -==== -Replace `myservername` with the server name that you used to xref:generate-selfsigned-root.adoc[generate your root certificate] -- unless you actually used the placeholder suggestion `myservername` from that procedure. -==== -. Generate a device certificate and public key, and sign it with the root CA that you created previously. -+ -[source,bash] ----- -include::example$start.sh[tags="genclientkeys"] ----- - -. Find out the address of the device gateway for your OTA Connect Account -+ -You can get this address from the `credentials.zip` that you download from the OTA Connect Portal. -+ -You need this address to get the internal root CA certificate of the device gateway. This certificate is also necessary to provision devices. - -.. If you haven't done so already, xref:generating-provisioning-credentials.adoc[download a provisioning key]. -.. Extract the contents of the `credentials.zip` file to a local folder. -.. In that folder, look for the file `autoprov` and open it with a text editor. -+ -You should see a URL that resembles the following example: -+ -`\https://946f68b8-13d2-4647-b335-5a48777b5657.tcpgw.prod01.advancedtelematic.com:443` -.. Make a note of this URL. - -. Get the device gateway's root certificate with the following openssl command: -+ ----- -export device_gateway= -openssl s_client -connect ${device_gateway}:8000 -servername $device_gateway -showcerts | \ - sed -n '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ${device_dir}/root.crt ----- -+ -Replace, the placeholder `` with URL that you noted in the previous step. -+ -. Make a note where the actual `$(device_dir)` is on your computer. -+ -You can quickly get it with the command `echo $(device_dir)`. Your device directory should resemble the following example: -+ -`myservername/devices/4e7cdc4f-b7dc-4fb0-900f-a237ba3e804c/` -. Once have noted your device directory, you can xref:enable-device-cred-provtest.adoc[install the test device certificate on the device]. -// end::install-root-ca[] diff --git a/docs/ota-client-guide/modules/ROOT/pages/intro-prod.adoc b/docs/ota-client-guide/modules/ROOT/pages/intro-prod.adoc deleted file mode 100644 index b669201cf1..0000000000 --- a/docs/ota-client-guide/modules/ROOT/pages/intro-prod.adoc +++ /dev/null @@ -1,44 +0,0 @@ -= Moving to Production -ifdef::env-github[] - -[NOTE] -==== -We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. -==== -endif::[] - -{product-name} is designed to integrate easily into development workflows: you build your image, push it, set auto-updates for some of your test-bench devices, and so on. But once you're ready to move from testing into production, you will likely want to do a few things differently. Here is a summary of our recommended workflow for moving from development to production. - -== Maintain separate accounts for development, testing and production - -There are (at least) two good reasons to separate your dev/testing accounts from production: - -* Isolation of production-ready deployments - -{product-name-short} does not support deleting devices or device images. We do this for auditability, but it does mean that your dev/testing account can end up getting a bit cluttered. You wouldn't want to accidentally select the wrong build on a production run. - -* Separation of responsibilities - -Chances are, your developer team isn't responsible for making the decision to push updates live. You can cross-deploy images that are ready for testing to a test account controlled by QA, then once again to an account for production once they've passed QA. - -''' - -To make this workflow possible, create an account for each environment you find useful (e.g. dev, QA, beta, production, etc.), and then read about xref:cross-deploy-images.adoc[using garage-deploy to cross-deploy images from one account to another]. - -== Manage your own chain(s) of trust - -When you create an account, and when you create provisioning credentials, we generate various keys for you. There's a xref:provisioning-methods-and-credentialszip.adoc[table here] listing everything that's in `credentials.zip`, but the main thing you need to know is that there are two root authorities that we initially generate: a root CA for authenticating your devices during provisioning, and a private key for signing the metadata of the images you build. We take the security of these keys/certificates extremely seriously: following industry best practices, they are kept in a link:https://www.vaultproject.io/[Vault] instance and only taken out when you request them. - -However, *we don't need to have the keys at all*. You can manage your own root CAs in both cases. Images you build get signed locally before being pushed, and {product-name-short} only needs to verify the signatures, and thus xref:enable-device-cred-provisioning.adoc#_use_a_hardware_security_module_hsm_when_provisioning_with_device_credentials[provision your devices with device credentials]. - -Once you've done that, we won't have any of your private key material at all. - -== Consider using a Hardware Security Module - -In the quickstart guides, we automatically provision your devices when they come online for the first time. To make this happen, the devices need to present a provisioning key. If the provisioning key is valid, then {product-name-short} bootstraps the provisioning process by negotiating unique, device-specific credentials in the form of X.509 certificates for mutual TLS authentication. It's these generated credentials that are used when the device connects to the server for updates. - -We refer to this method as provisioning with "shared" credentials. Although each device eventually receives device-specific credentials, the process begins with a shared credential: the provisioning key. - -{product-name} also supports provisioning with pre-loaded device credentials. In this case, the device is pre-loaded with the requisite bootstrap credentials, signed by a root CA of your choice. These can be stored in the HSM, obviating the need for a provisioning key on the device that could potentially be compromised, and also obviating the need for us to hold key material for provisioning. - -How the HSM for your individual board or device works is up to you, but you can xref:enable-device-cred-provisioning.adoc#_simulate_the_provisioning_process_with_device_credentials[simulate a hardware security module in QEMU] to get an idea of how the process works. We provide instructions for QEMU HSM provisioning only; if you need development support in adapting the instructions to your own board, link:mailto:otaconnect.support@here.com[contact us for a consultation]. diff --git a/docs/ota-client-guide/modules/ROOT/pages/provide-testroot-cert.adoc b/docs/ota-client-guide/modules/ROOT/pages/provide-testroot-cert.adoc deleted file mode 100644 index 430888ee9d..0000000000 --- a/docs/ota-client-guide/modules/ROOT/pages/provide-testroot-cert.adoc +++ /dev/null @@ -1,21 +0,0 @@ -= Register your test root certificate -ifdef::env-github[] - -[NOTE] -==== -We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. -==== -endif::[] - - -//MC: This is a copy of the topic "provide-root-cert.adoc" but intended for the "test" use case. Need to use more includes to reduce redundancy - -Once you have a root certificate, you need to have it registered with your account so that the OTA Connect server can verify your device certificates. - -* To register your test root certificate with HERE OTA Connect, send it to link:mailto:otaconnect.support@here.com[otaconnect.support@here.com]. - -If you followed our recommendations, you should have one OTA Connect account for testing and another for production. Make sure that you specify that this certificate is for your *test* account. - -* While you wait for confirmation from the OTA Connect support team, you can already xref:generatetest-devicecert.adoc[generate a test device certificate]. - -* Once you've received confirmation that the root certificate has been registered, you can xref:enable-device-cred-provtest.adoc[enable device-credential provisioning and install the certificate] on a test device. \ No newline at end of file diff --git a/docs/ota-client-guide/modules/ROOT/pages/secure-software-updates-test.adoc b/docs/ota-client-guide/modules/ROOT/pages/secure-software-updates-test.adoc deleted file mode 100644 index 4d38193000..0000000000 --- a/docs/ota-client-guide/modules/ROOT/pages/secure-software-updates-test.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= Test software update security -ifdef::env-github[] - -[NOTE] -==== -We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. -==== -endif::[] - - -//MC: This is a copy of the topic "secure-software-updates.adoc" but intended for the "test" use case. Need to use more includes to reduce redundancy. - -To secure your software updates, OTA Connect ensures that all software files have accompanying metadata that is signed according to the Uptane framework. - -When evaluating OTA Connect you don't have to worry about signing this metadata yourself. The OTA Connect server automatically signs the metadata after you upload software. - -However, for this process to work, the OTA Connect server must host the xref:pki.adoc[private keys] that are used to sign the metadata. This is a security risk -- if an attacker is able to infiltrate the OTA Connect server, they can use these private keys to sign metadata for malicious software and send it to your devices. - -To prevent an event like this from happening, you should take these private keys offline and sign the metadata in your development environment. Then you can push the signed metadata back to the server. To do this, you use the `garage-sign` command which is part of our xref:install-garage-sign-deploy.adoc[`garage-deploy`] tool. diff --git a/docs/ota-client-guide/modules/ROOT/pages/update-your-client-configuration.adoc b/docs/ota-client-guide/modules/ROOT/pages/update-your-client-configuration.adoc deleted file mode 100644 index a43de050bb..0000000000 --- a/docs/ota-client-guide/modules/ROOT/pages/update-your-client-configuration.adoc +++ /dev/null @@ -1,44 +0,0 @@ -= Recommended client configurations -ifdef::env-github[] - -[NOTE] -==== -We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. -==== -endif::[] - - -Before you start developing or deploying to production, you should check that your configuration file has appropriate settings for your use case. - -For more details about the full client configuration settings, see the xref:aktualizr-config-options.adoc[client configuration reference]. - -== Recommended settings for development - -[cols="1,1,1a",options="header,footer"] -|==================== -|Name | Default | Description -|`polling_sec` | `10` | -Interval between polls (in seconds). - -The default polling internal designed to make it convenient for you test and develop OTA update functions. -|`force_install_completion` | `true` | -Forces installation completion. Causes a system reboot in case of an ostree package manager. Emulates a reboot in case of a fake package manager. - -You'll want to set this to `true` when developing because it's more convenient. - -|==================== - -== Recommended settings for production - -[cols="1,1,1a",options="header,footer"] -|==================== -|Name | Default | Description -|`polling_sec` | `86400` | When moving to production you'll want to have a much longer interval. -In fact, for production, we don't support intervals less the 1 hour (3,600 seconds). Longer internals help you to reduce the internet bandwidth and power consumption for your devices. - -We recommend an internal between 1 and 7 days (86,400 to 604,800 seconds). -|`force_install_completion` | `false` | -If you followed our recommendation to enable automatic rebooting for development, you should turn it off again for production. -|==================== - - From df5f3a4ca882ba5ba397e4e54f743ba14aee5181 Mon Sep 17 00:00:00 2001 From: Jon Oster Date: Mon, 27 Jan 2020 11:05:52 +0100 Subject: [PATCH 14/14] DOCS: Fix invalid anchor tag; content was moved to another page Signed-off-by: Jon Oster Signed-off-by: Mike Sul --- .../ROOT/pages/add-ota-functonality-existing-yocto-project.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc b/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc index ac07c920e2..502e52102e 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc @@ -16,7 +16,7 @@ endif::[] If you already have a Yocto-based project, you can start your functional integration with {product-name} by following these four steps: 1. Clone the https://github.com/advancedtelematic/meta-updater[meta-updater] layer and add it to your https://www.yoctoproject.org/docs/2.6/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf[bblayers.conf]. -2. Clone a BSP integration layer (`meta-updater-$\{PLATFORM}`, e.g. https://github.com/advancedtelematic/meta-updater-raspberrypi[meta-updater-raspberrypi]) and add it to your `conf/bblayers.conf`. If your board isn't supported yet, you could write a BSP integration for it yourself. See the <> section for the details. +2. Clone a BSP integration layer (`meta-updater-$\{PLATFORM}`, e.g. https://github.com/advancedtelematic/meta-updater-raspberrypi[meta-updater-raspberrypi]) and add it to your `conf/bblayers.conf`. If your board isn't supported yet, you could write a BSP integration for it yourself. See xref:supported-boards.adoc#_adding_support_for_your_board[Adding support for your board] for more details. 3. Set up your https://www.yoctoproject.org/docs/2.6/ref-manual/ref-manual.html#var-DISTRO[distro]. If you are using "poky", the default distro in Yocto, you can change it in your `conf/local.conf` to `poky-sota` or to `poky-sota-systemd`. Alternatively, if you are using your own or a third-party distro configuration, you can add the following parameters to it, thus combining the capabilities of your distro with meta-updater features. + ----