Doc/2020.2/merge 2020.1 and master (#1545)

Doc/2020.2/merge 2020.1 and master

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

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]

docs/ota-client-guide/modules/ROOT/pages/_partials/why-different-prov-methods.adoc

@@ -1,6 +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 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".
 
-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].

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 <<Adding support for your board>> 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.
 +
 ----

docs/ota-client-guide/modules/ROOT/pages/client-provisioning-methods.adoc

@@ -14,67 +14,77 @@ 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".
+== What is device provisioning?
 
-* *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.
+OTA Connect uses mutual TLS for transport security and device authentication. This means that:
+
+* 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.
+
+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.
+
+*Device provisioning*, therefore, is simply the process of providing a device with:
 
-.How the server roles change depending on which method you choose:
-[caption="Figure 1: "]
-image::img::prov-diff-infra.png[]
+* 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
 
-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.
+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.
 
-Let's take a close look at how each method works.
 
 == Provisioning with shared credentials
 
-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:
+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 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 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 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.
+
+.Summary of Shared credential provisioning
+image::img::shared-cred-provisioning.png[width=100%]
 
 == 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.
+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.
++
+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.
 
-The following diagram summarizes the differences in how devices are provisioned between the two methods.
+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.
 
-.How the server roles change depending on which method you choose:
-[caption="Figure 2: "]
-image::img::prov-diff-devices.png[]
+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 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.
+.Summary of Device credential provisioning
+image::img::device-cred-provisioning.png[width=100%]
 
 == 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, 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:
 
 * 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.
-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.
+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.