-
Notifications
You must be signed in to change notification settings - Fork 60
OTA-2613 Clean up "aktualizr/docs/ " folder #1208
Conversation
ea2f2de
to
9d9ec4e
Compare
Codecov Report
@@ Coverage Diff @@
## master #1208 +/- ##
==========================================
- Coverage 85.59% 79.26% -6.34%
==========================================
Files 231 168 -63
Lines 17392 10005 -7387
==========================================
- Hits 14886 7930 -6956
+ Misses 2506 2075 -431
Continue to review full report at Codecov.
|
15fb65e
to
613e023
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There may also be some information from the deleted docs that may still be useful to carry over. And there's still plenty of code changes, but I assume that'll be a separate branch/PR.
@patrickvacek Can you take another look and see if it's OK to merge? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I can confirm everything you've marked as fixed, but a few issues still stand.
|
||
When you provision with device credentials, you install permanent credentials each device before the device connects to the server. Unlike shared-credential provisioning, the server doesn't issue any credentials to devices. Instead, you use a root CA certificate to sign the credentials that you install on the device. You then install the same root CA certificate on the OTA Connect server. | ||
|
||
Every time the device attempts to connect, the server verifies that the device credentials are signed by the same CA that you originally installed on the server. The device also verifies that is communicating with a genuine {product-name} server. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still a problem.
|
||
== Use a Hardware Security Module (HSM) When Provisioning with Device Credentials | ||
|
||
As described in the link:prod-intro.html[introduction], it's a good idea to use a Hardware Security Model (HSM) to hold potentially sensitive device credentials. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still broken.
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 use an HSM when provisioning with device credentials, follow these steps: :: | ||
. link:generate-and-install-a-root-certificate.html[Generate and install a root certificate]. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still broken.
|
||
''' | ||
|
||
link:./provisioning-methods-and-credentialszip.html[More information] is available on provisioning with shared credentials, device credentials (with or without an HSM), and how the various files included in `credentials.zip` are related. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still broken.
docs/integrate-libaktualizr.adoc
Outdated
|
||
// TODO MERLIN: Figure out if we even want to try to document this beyond what is mentioned on the introduction page. Frankly, I think I doubt it. If you're using libaktualizr, what you probably want is code, doxygen docs, and the example hmi_stub app. Anything we can add here might just be cruft. | ||
|
||
// MC: I think we can add valuable content rather than cruft. We'll need some standard "getting started" content (For reference, see the Tracking C client library: https://docs.in.here.com/ci/location_tracking_c/hlp/1.0.0/ed15c72/html/dev_guide/#topics/getting-started.html ) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still valid.
|
||
// MC: I think we can add valuable content rather than cruft. We'll need some standard "getting started" content (For reference, see the Tracking C client library: https://docs.in.here.com/ci/location_tracking_c/hlp/1.0.0/ed15c72/html/dev_guide/#topics/getting-started.html ) | ||
|
||
The aktualizr client is designed to be run as a standalone component on an embedded system and can manage the entire software update process. However, you might have requirements that got beyond what the standalone client can provide. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still needs correction.
docs/integrate-libaktualizr.adoc
Outdated
For this purpose, you can also use libaktualizr to make your own OTA update client. Typical scenarios for making your own client could be: | ||
|
||
* You want to integrate {product-name} functionality with a third-party HMI | ||
* You want to integrate {product-name} with a third-party interface that installs software on secondary ECUs |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still broken.
docs/integrate-libaktualizr.adoc
Outdated
* You want to constrain network traffic and software updates to specific vehicle states | ||
* You want to provide motorists or service staff with progress indicators for specific software updates. | ||
|
||
To get started with libaktualizr see the link:..src/hmi_stub[reference client] and the https://advancedtelematic.github.io/aktualizr/class_aktualizr.html[reference documentation]. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still broken.
|
||
1. The user downloads a package that contains an initial provisioning key. This is installed on all devices and is only used to bootstrap the provisioning process. | ||
2. When Aktualizr first runs on a device, it uses this key/certificate to make a request to the device gateway https API. The server registers the new device and returns a PKCS#12 archive containing the real credentials for the device. | ||
3. The device unpacks the root CA certificate and client certificate from this bundle into the paths specified in the `[storage]` section of the config. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This might not be your fault, but actually they don't get unpacked anywhere except in memory. I would say instead "the device reads the root CA certificate and client certificate from this bundle".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@patrickvacek I fixed all the issues that I understood. I fixed the broken links, the file name, and stripped out unnecessary comments.
Sorry for being a dunce, but in some instances when you say stuff is "still broken" and "still valid" I don't know what you're referring to. In many cases the content looks fine to me. Basically all the issues that don't concern broken links or comments.
Unrelated to the content but it would be nice to do a bit of git clean up before merging:
Recommendation: rebase everything onto master and squash the first three and the last two commits together. |
1d206c0
to
91d13ae
Compare
91d13ae
to
9b699e3
Compare
This is part of the wider task of implementing renaming. I replace topics that I consider to be duplicates of what is in the docs repo. I indicated this in a comment at the top of the file. The replacements contain the new terminology. I also updated the terminology in the "non-duplicate" files. Signed-off-by: Merlin Carter <merlin.carter@here.com> Signed-off-by: Patrick Vacek <patrickvacek@gmail.com>
9b699e3
to
623da35
Compare
I found a couple small things that slipped through our review, so I fixed them. A couple other things outside the scope of this PR that should still get fixed:
|
@patrickvacek Thanks for helping with the stray issues. I will also address the other issues that you raised - as part of this ticket: https://saeljira.it.here.com/browse/OTA-2750. Can the PR be approved and merged now? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep, done!
This is part of the wider task of implementing renaming. I replace topics that I consider to be duplicates of what is in the docs repo. In such cases, I indicate the original file in a comment at the top of the file. The replacements contain the new terminology. I also updated the terminology in the "non-duplicate" files.