Merge pull request #1220 from advancedtelematic/refactor/OTA-2797/pro…

…vision-rename

Refactor/ota 2797/provision rename

CHANGELOG.md

@@ -6,6 +6,10 @@ Our versioning scheme is `YEAR.N` where `N` is incremented whenever a new releas
 
 ## [??? (unreleased)]
 
+### Changed
+
+- Provisioning methods have been renamed. "Autoprovisioning" or "automatic provisioning" is now known as "shared credential provisioning". "Implicit provisioning" is now known as "device credential provisioning". "HSM provisioning" was always a misnomer, so it is now refered to as "device credential provisioning with an HSM". [PR](https://github.com/advancedtelematic/aktualizr/pull/1220)
+
 ## [2019.3] - 2019-04-29
 
 ### Added

README.adoc

@@ -148,7 +148,7 @@ Note that, by default, the compilation and tests run in sequence and the output
 CTEST_OUTPUT_ON_FAILURE=1 CTEST_PARALLEL_LEVEL=8 make -j8 qa
 ----
 
-Some tests require additional setups, such as code coverage, HSM emulation or provisioning credentials (link:docs/credentials.adoc[credentials.adoc]). The exact reference about these steps is the link:scripts/test.sh[main test script] used for CI. It is parametrized by a list of environment variables and is used by our CI environments. To use it, run it in the project's root directory:
+Some tests require additional setups, such as code coverage, HSM emulation or provisioning credentials (link:docs/provisioning-methods-and-credentialszip.adoc[]). The exact reference about these steps is the link:scripts/test.sh[main test script] used for CI. It is parametrized by a list of environment variables and is used by our CI environments. To use it, run it in the project's root directory:
 
 ----
 ./scripts/test.sh
@@ -226,7 +226,7 @@ Some more detailed instructions on how to configure a fake device can be found o
 
 === Provisioning
 
-If you intend to use aktualizr to authenticate with a server, you will need some form of provisioning. Aktualizr currently supports two methods of provisioning: link:docs/automatic-provisioning.adoc[automatic] and link:docs/implicit-provisioning.adoc[implicit]. You can also implicitly provision link:docs/hsm-provisioning.adoc[by using an HSM]. You can learn more about the credentials files used to support provisioning in link:docs/credentials.adoc[].
+If you intend to use aktualizr to authenticate with a server, you will need some form of provisioning. Aktualizr currently supports provisioning with shared credentials or with device credentials. Device credential provisioning supports using an HSM to store private keys. The differences and details are explained in link:docs/client-provisioning-methods.adoc[] and link:docs/provision-with-device-credentials.adoc[]. You can learn more about the credentials files used to support provisioning in link:docs/provisioning-methods-and-credentialszip.adoc[].
 
 == Maintainers
 

actions.md

@@ -23,13 +23,13 @@ These are the primary actions that a user of libaktualizr can perform through th
     - [x] Update is not in pending state anymore after successful finalization (aktualizr_test.cc)
     - [x] Update is not in pending state anymore after failed finalization (aktualizr_test.cc)
   - [x] Provision with the server
-    - [x] Automatically provision (OTA-983, uptane_init_test.cc, uptane_ci_test.cc, auto_prov_test.py)
+    - [x] Provision with shared credentials (OTA-983, uptane_init_test.cc, uptane_ci_test.cc, shared_cred_prov_test.py)
       - [x] Extract credentials from a provided archive (config_test.cc, utils_test.cc)
       - [x] Parse a p12 file containing TLS credentials (crypto_test.cc)
       - [x] aktualizr possesses all necessary credentials after provisioning (OTA-987, uptane_key_test.cc)
-    - [x] Implicitly provision (OTA-996, OTA-1210, config_test.cc, uptane_implicit_test.cc, uptane_test.cc, implicit_prov_test.py)
-      - [x] Fail if TLS credentials are unavailable (OTA-1209, uptane_implicit_test.cc)
-    - [x] Implicitly provision with keys accessed via PKCS#11 (hsm_prov_test.py)
+    - [x] Provision with device credentials (OTA-996, OTA-1210, config_test.cc, device_cred_prov_test.cc, uptane_test.cc, device_cred_prov_test.py)
+      - [x] Fail if TLS credentials are unavailable (OTA-1209, device_cred_prov_test.cc)
+    - [x] Provision with device credentials using keys accessed via PKCS#11 (device_cred_prov_hsm_test.py)
       - [x] Generate RSA keypairs via PKCS#11 (crypto_test.cc, keymanager_test.cc)
       - [x] Read a TLS certificate via PKCS#11 (crypto_test.cc)
       - [x] Sign and verify a file with RSA via PKCS#11 (crypto_test.cc, keymanager_test.cc)
@@ -283,9 +283,9 @@ This is just the list of sequences currently covered. It is likely that there ar
 - [x] Initialize -> CheckUpdates -> Download -> updates downloaded but not installed (aktualizr_test.cc)
 - [x] Initialize -> Install -> nothing to install (aktualizr_test.cc)
 - [x] Initialize -> CheckUpdates -> Download -> Install -> updates installed (aktualizr_test.cc)
-- [x] Autoprovision with real server. Initialize -> CheckUpdates -> verify state with aktualizr-info (auto_prov_test.py)
-- [x] Implicitly provision with real server. Initialize -> verify not provisioned with aktualizr-info -> run aktualizr-cert-provider -> Initialize -> CheckUpdates -> verify state with aktualizr-info (implicit_prov_test.py)
-- [x] Implicitly provision with HSM with real server. Initialize -> verify not provisioned with aktualizr-info -> run aktualizr-cert-provider -> Initialize -> CheckUpdates -> verify state with aktualizr-info (hsm_prov_test.py)
+- [x] Provision with shared credentials with real server. Initialize -> CheckUpdates -> verify state with aktualizr-info (shared_cred_prov_test.py)
+- [x] Provision with device credentials with real server. Initialize -> verify not provisioned with aktualizr-info -> run aktualizr-cert-provider -> Initialize -> CheckUpdates -> verify state with aktualizr-info (device_cred_prov_test.py)
+- [x] Provision with device credentials with real server using an HSM. Initialize -> verify not provisioned with aktualizr-info -> run aktualizr-cert-provider -> Initialize -> CheckUpdates -> verify state with aktualizr-info (device_cred_prov_hsm_test.py)
 
 
 ## aktualizr tools
@@ -365,12 +365,12 @@ These tools all link with libaktualizr, although they do not necessary use the A
 
 ### aktualizr-cert-provider
 
-`aktualizr-cert-provider` assists with generating credentials and uploading them to a device for implicit provisioning.
+`aktualizr-cert-provider` assists with generating credentials and uploading them to a device for device credential provisioning.
 
 - [x] Use file paths from config if provided (cert_provider_test.cc)
-- [x] Use autoprovisioning credentials if fleet CA and private key are not provided (cert_provider_autoprov_test.cc)
+- [x] Use shared provisioning credentials if fleet CA and private key are not provided (cert_provider_shared_cred_test.cc)
   - [x] Generate a random device ID (OTA-986, utils_test.cc, uptane_init_test.cc)
-  - [x] Automatically provision (cert_provider_autoprov_test.cc)
+  - [x] Provision with shared credentials (cert_provider_shared_cred_test.cc)
 - [x] Use fleet credentials if provided (cert_provider_test.cc)
   - [x] Abort if fleet CA is provided without fleet private key (cert_provider_test.cc)
   - [x] Abort if fleet private key is provided without fleet CA (cert_provider_test.cc)
@@ -390,12 +390,12 @@ These tools all link with libaktualizr, although they do not necessary use the A
   - [x] Serialize device certificate to a string (cert_provider_test.cc)
 - [ ] Read server root CA from credentials archive
   - [ ] Read server root CA from server_ca.pem if present (to support community edition use case)
-  - [x] Read server root CA from p12 (cert_provider_autoprov_test.cc)
+  - [x] Read server root CA from p12 (cert_provider_shared_cred_test.cc)
 - [x] Write credentials to a local directory if requested (cert_provider_test.cc)
   - [x] Provide device private key (cert_provider_test.cc)
   - [x] Provide device certificate (cert_provider_test.cc)
-  - [x] Provide root CA if requested (cert_provider_autoprov_test.cc)
-  - [x] Provide server URL if requested (cert_provider_autoprov_test.cc)
+  - [x] Provide root CA if requested (cert_provider_shared_cred_test.cc)
+  - [x] Provide server URL if requested (cert_provider_shared_cred_test.cc)
 - [ ] Copy credentials to a device with ssh
   - [ ] Create parent directories
   - [ ] Provide device private key
@@ -527,9 +527,9 @@ These tools also use libaktualizr, but only for common utility functions. They a
 - [x] Run garage-sign
 - [x] Build credentials into an image
 - [x] Run aktualizr-cert-provider
-- [x] Build an image with automatic provisioning that provisions successfully
-- [x] Build an image with implicit provisioning that provisions successfully
-- [x] Build an image with implicit provisioning using an HSM that provisions successfully
+- [x] Build an image with shared credential provisioning that provisions successfully
+- [x] Build an image with device credential provisioning that provisions successfully
+- [x] Build an image with device credential provisioning using an HSM that provisions successfully
 - [x] Build an image with manual control that provisions successfully
 - [x] Build an image for Raspberry Pi
 - [x] Build an image using grub as a bootloader that provisions successfully

config/CMakeLists.txt

@@ -5,7 +5,7 @@ if(BUILD_DEB)
         PERMISSIONS OWNER_READ OWNER_WRITE
         COMPONENT aktualizr)
 
-    install(FILES sota_ubuntu.toml
+    install(FILES sota-ubuntu.toml
         DESTINATION lib/sota/conf.d
         PERMISSIONS OWNER_READ OWNER_WRITE
         COMPONENT aktualizr)

docs/client-provisioning-methods.adoc

@@ -23,10 +23,10 @@ To configure a device to provision with shared credentials, follow these steps:
 . Download a https://docs.ota.here.com/quickstarts/generating-provisioning-credentials.html[provisioning key].
 . Edit the following `.toml` configuration file:
 +
-link:../config/sota_autoprov.toml[config/sota_autoprov.toml]
+link:../config/sota-shared-cred.toml[config/sota-shared-cred.toml]
 . Update the configuration file with the path to the zip file that you saved in the first step and start Aktualizr on the device.
 +
-** When aktualizr starts, it uses the provisioning key to register with the device gateway HTTPS API. 
+** When aktualizr starts, it uses the provisioning key to register with the device gateway HTTPS API.
 ** The server registers the new device and returns a PKCS#12 archive containing the real credentials for the device. This archive contains the root CA certificate and client certificate.
 ** The device unpacks the archive into the paths that are specified in the `[storage]` section of the config.
 ** The device uses this private key and certificate for all further communication with the server.

docs/configuration.adoc

@@ -65,7 +65,7 @@ Options for how the device is provisioned with the backend.
 | `server`                    |           | Server provisioning URL. If empty, set to `tls.server`.
 | `p12_password`              |           | Password for PKCS#12 encryption.
 | `expiry_days`               | `"36000"` | Provided in the `ttl` field of the device provisioning request sent to the server.
-| `provision_path`            |           | Path to an archive containing provisioning data. See link:{aktualizr-github-url}/docs/credentials.adoc[] for the specification of the contents of this file.
+| `provision_path`            |           | Path to an archive containing provisioning data. See link:{aktualizr-github-url}/docs/provisioning-methods-and-credentialszip.adoc[] for the specification of the contents of this file.
 | `device_id`                 |           | Device ID of the primary ECU. If left empty, a random name will be generated.
 | `primary_ecu_serial`        |           | Serial number of the primary ECU. If left empty, a random serial will be generated.
 | `primary_ecu_hardware_id`   |           | The hardware ID of the primary ECU (e.g., `"raspberry-pi"`). If left empty, the hostname of the device will be used.

docs/debugging-tips.adoc

@@ -2,11 +2,11 @@
 
 == Running Aktualizr in development
 
-The `sota_local.toml` configuration file sets the package manager to `PackageManagerFake`, which allows the installation process to be tested locally:
+The `sota-local.toml` configuration file sets the package manager to `PackageManagerFake`, which allows the installation process to be tested locally:
 
     # From the build directory
     mkdir sota-prov
-    src/aktualizr_primary/aktualizr --config ../config/sota_local.toml
+    src/aktualizr_primary/aktualizr --config ../config/sota-local.toml
 
 For VS code, there is a `launch.json` provided in the `.vscode` directory.  This assumes that the cmake build directory is `build`.
 

docs/provision-with-device-credentials.adoc

@@ -22,14 +22,14 @@ To simulate provisioning with a device certificate, follow these steps: ::
 1. Add the following lines to your local.conf:
 +
 ----
-SOTA_CLIENT_PROV = "aktualizr-ca-implicit-prov"
+SOTA_CLIENT_PROV = "aktualizr-device-prov"
 SOTA_DEPLOY_CREDENTIALS = "0"
 ----
 
 1. Build a standard image using the bitbake command.
 1. Boot the image.
 +
-The device should not automatically provision its credentials. To verify this, log in to the OTA Connect server and make sure that the device does not appear in the list of devices.
+The device should not be able to provision at this time. To verify this, log in to the OTA Connect server and make sure that the device does not appear in the list of devices.
 1. Load the device credentials on to the device with `aktualizr-cert-provider` command:
 +
 ----

docs/provisioning-methods-and-credentialszip.adoc

@@ -29,9 +29,6 @@ The following files are present in credentials.zip:
 
 As you can see, the relevant files for the device itself are `autoprov_credentials.p12` and `autoprov.url`.
 
-When you link:./provision-with-device-credentials.adoc#use-a-hardware-security-module-hsm-when-provisioning-with-device-credentials[Use a Hardware Security Module (HSM)] to provisioning with device credentials, the `implicit_writer` function in meta-updater takes over. The initial credentials on the device won't be valid; this is why you need to copy in the generated ones after booting it.
-
-
 == Configuration options for provisioning with shared credentials
 
 When provisioning with shared credentials, the process works as follows:
@@ -54,7 +51,7 @@ The following items are relevant for this process:
 | Primary ECU Hardware ID | Automatically generated by Aktualizr
 |===================
 
-An example `.toml` configuration file can be found at link:../config/sota_autoprov.toml[]. This is what is used by the `aktualizr-auto-prov` recipe in meta-updater.
+An example `.toml` configuration file can be found at link:../config/sota-shared-cred.toml[]. This is what is used by the `aktualizr-shared-cred-prov` recipe in meta-updater.
 
 == Configuration options for provisioning with device credentials
 

scripts/export_to_hsm.sh

@@ -12,8 +12,8 @@ softhsm2-util --init-token --slot 0 --label "Virtual token" --pin 1234 --so-pin
 SLOT=$(softhsm2-util --show-slots | grep -m 1 -oP 'Slot \K[0-9]+')
 echo "Initialized token in slot: $SLOT"
 
-openssl x509 -outform der -in "${CERTS_DIR}/client.pem" -out "${CERTS_DIR}/implicit_client.der"
-pkcs11-tool --module="${TEST_PKCS11_MODULE_PATH}" --id 1 --write-object "${CERTS_DIR}/implicit_client.der" --type cert --login --pin 1234
+openssl x509 -outform der -in "${CERTS_DIR}/client.pem" -out "${CERTS_DIR}/client.der"
+pkcs11-tool --module="${TEST_PKCS11_MODULE_PATH}" --id 1 --write-object "${CERTS_DIR}/client.der" --type cert --login --pin 1234
 
 openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in "${CERTS_DIR}/pkey.pem" -out "${CERTS_DIR}/priv.p8"
 softhsm2-util --import "${CERTS_DIR}/priv.p8" --label "uptane" --id 02 --slot "$SLOT" --pin 1234

scripts/setup_hsm.sh

@@ -19,9 +19,9 @@ mkdir -p "${TOKEN_DIR}"
 softhsm2-util --init-token --slot 0 --label "Virtual token" --pin 1234 --so-pin 1234
 SLOT=$(softhsm2-util --show-slots | grep -m 1 -oP 'Slot \K[0-9]+')
 echo "Initialized token in slot: $SLOT"
-softhsm2-util --import "${DATA_DIR}/implicit/pkey.pem" --label "pkey" --id 02 --slot "$SLOT" --pin 1234
-openssl x509 -outform der -in "${DATA_DIR}/implicit/client.pem" -out "${TMPDIR}/implicit_client.der"
-pkcs11-tool --module="${TEST_PKCS11_MODULE_PATH}" --id 1 --write-object "${TMPDIR}/implicit_client.der" --type cert --login --pin 1234
+softhsm2-util --import "${DATA_DIR}/device_cred_prov/pkey.pem" --label "pkey" --id 02 --slot "$SLOT" --pin 1234
+openssl x509 -outform der -in "${DATA_DIR}/device_cred_prov/client.pem" -out "${TMPDIR}/client.der"
+pkcs11-tool --module="${TEST_PKCS11_MODULE_PATH}" --id 1 --write-object "${TMPDIR}/client.der" --type cert --login --pin 1234
 
 openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in "${DATA_DIR}/priv.key" -out "${TMPDIR}/priv.p8"
 softhsm2-util --import "${TMPDIR}/priv.p8" --label "uptane" --id 03 --slot "$SLOT" --pin 1234

src/aktualizr_info/aktualizr_info_config_test.cc

@@ -11,7 +11,7 @@ TEST(aktualizr_info_config, config_initialized_values) {
 }
 
 TEST(aktualizr_info_config, config_toml_parsing) {
-  AktualizrInfoConfig conf("config/sota_autoprov.toml");
+  AktualizrInfoConfig conf("config/sota-shared-cred.toml");
 
   EXPECT_EQ(conf.storage.type, StorageType::kSqlite);
   EXPECT_EQ(conf.storage.sqldb_path.get(conf.storage.path), "/var/sota/sql.db");

src/aktualizr_primary/main.cc

@@ -36,7 +36,7 @@ bpo::variables_map parse_options(int argc, char *argv[]) {
       ("config,c", bpo::value<std::vector<boost::filesystem::path> >()->composing(), "configuration file or directory")
       ("loglevel", bpo::value<int>(), "set log level 0-5 (trace, debug, info, warning, error, fatal)")
       ("run-mode", bpo::value<std::string>(), "run mode of aktualizr: full, once, campaign_check, campaign_accept, check, download, or install")
-      ("tls-server", bpo::value<std::string>(), "url, used for auto provisioning")
+      ("tls-server", bpo::value<std::string>(), "url of device gateway")
       ("repo-server", bpo::value<std::string>(), "url of the uptane repo repository")
       ("director-server", bpo::value<std::string>(), "url of the uptane director repository")
       ("ostree-server", bpo::value<std::string>(), "url of the ostree repository")

src/aktualizr_repo/run/create_repo.sh

@@ -61,7 +61,7 @@ gen_site_conf () {
         cat <<EOF >${repo_dir}/site.conf
 OSTREE_REPO = "${repo_dir}/ostree"
 SOTA_PACKED_CREDENTIALS = "${repo_dir}/credentials.zip"
-SOTA_CLIENT_PROV = "aktualizr-ca-implicit-prov"
+SOTA_CLIENT_PROV = "aktualizr-device-prov"
 SOTA_CACERT_PATH = "${repo_dir}/certs/client/cacert.pem"
 SOTA_CAKEY_PATH = "${repo_dir}/certs/client/ca.private.pem"
 EOF

src/aktualizr_secondary/uptane_test.cc

@@ -39,7 +39,7 @@ TEST(aktualizr_secondary_uptane, credentialsPassing) {
   config.storage.path = temp_dir.Path();
   boost::filesystem::copy_file("tests/test_data/cred.zip", (temp_dir / "cred.zip").string());
   config.provision.provision_path = temp_dir / "cred.zip";
-  config.provision.mode = ProvisionMode::kAutomatic;
+  config.provision.mode = ProvisionMode::kSharedCred;
   config.provision.primary_ecu_serial = "testecuserial";
   config.uptane.director_server = http->tls_server + "/director";
   config.uptane.repo_server = http->tls_server + "/repo";

src/cert_provider/CMakeLists.txt

@@ -14,17 +14,14 @@ install(TARGETS aktualizr-cert-provider RUNTIME DESTINATION bin)
 add_aktualizr_test(NAME aktualizr_cert_provider SOURCES cert_provider_test.cc PROJECT_WORKING_DIRECTORY ARGS $<TARGET_FILE:aktualizr-cert-provider>)
 
 if (SOTA_PACKED_CREDENTIALS)
-
-  add_aktualizr_test(NAME aktualizr_cert_provider_auto_prov SOURCES cert_provider_autoprov_test.cc
-    PROJECT_WORKING_DIRECTORY ARGS $<TARGET_FILE:aktualizr-cert-provider> ${SOTA_PACKED_CREDENTIALS})
-
-  set_tests_properties(test_aktualizr_cert_provider_auto_prov PROPERTIES LABELS "credentials")
-
+    add_aktualizr_test(NAME aktualizr_cert_provider_shared_cred SOURCES cert_provider_shared_cred_test.cc
+        PROJECT_WORKING_DIRECTORY ARGS $<TARGET_FILE:aktualizr-cert-provider> ${SOTA_PACKED_CREDENTIALS})
+    set_tests_properties(test_aktualizr_cert_provider_shared_cred PROPERTIES LABELS "credentials")
 endif(SOTA_PACKED_CREDENTIALS)
 
 aktualizr_source_file_checks(${AKTUALIZR_CERT_PROVIDER_SRC}
                              ${AKTUALIZR_CERT_HEADERS}
-                             cert_provider_autoprov_test.cc
+                             cert_provider_shared_cred_test.cc
                              cert_provider_test.cc
                              cert_provider_test.h)