Skip to content
This repository has been archived by the owner on May 21, 2024. It is now read-only.

Latest commit

 

History

History
546 lines (498 loc) · 34.9 KB

actions.md

File metadata and controls

546 lines (498 loc) · 34.9 KB
Raw

libaktualizr

External actions

These are the primary actions that a user of libaktualizr can perform through the API.

  • Initialization
    • Set boot count to 0 to indicate successful boot
    • Detect a system reboot on the Primary, if expected (bootloader_test.cc)
    • Initialize Secondaries
      • Add Secondaries from configuration (uptane_test.cc)
        • Parse Secondary config files in JSON format (config_test.cc)
        • Create Secondary object
          • Create a virtual Secondary for testing (uptane_secondary_test.cc)
      • Add Secondaries via API (aktualizr_test.cc)
      • Adding multiple Secondaries with the same serial throws an error (uptane_test.cc)
    • Initialize device ID
      • Use a provided device ID (OTA-985, uptane_init_test.cc)
      • Generate a random device ID (OTA-986, utils_test.cc, uptane_init_test.cc)
    • Finalize a pending update that requires reboot (aktualizr_test.cc)
      • Store installation result (aktualizr_test.cc)
      • Send manifest (aktualizr_test.cc)
      • Update is not in pending state anymore after successful finalization (aktualizr_test.cc)
      • Update is not in pending state anymore after failed finalization (aktualizr_test.cc)
    • Provision with the server
      • Provision with shared credentials (OTA-983, uptane_init_test.cc, uptane_ci_test.cc, shared_cred_prov_test.py)
        • Extract credentials from a provided archive (config_test.cc, utils_test.cc)
        • Parse a p12 file containing TLS credentials (crypto_test.cc)
        • aktualizr possesses all necessary credentials after provisioning (OTA-987, uptane_key_test.cc)
      • Provision with device credentials (OTA-996, OTA-1210, config_test.cc, device_cred_prov_test.cc, uptane_test.cc, device_cred_prov_test.py)
        • Fail if TLS credentials are unavailable (OTA-1209, device_cred_prov_test.cc)
      • Provision with device credentials using keys accessed via PKCS#11 (device_cred_prov_hsm_test.py)
        • Generate RSA keypairs via PKCS#11 (crypto_test.cc, keymanager_test.cc)
        • Read a TLS certificate via PKCS#11 (crypto_test.cc)
        • Sign and verify a file with RSA via PKCS#11 (crypto_test.cc, keymanager_test.cc)
    • Initialize Primary ECU keys
      • Generate Primary ECU keys (OTA-989, uptane_serial_test.cc)
        • Generate RSA 2048 key pairs (crypto_test.cc)
        • Generate RSA 4096 key pairs (crypto_test.cc)
        • Generate ED25519 key pairs (crypto_test.cc)
    • Initialize Primary ECU serial
      • Use a provided Primary serial (OTA-988, config_test.cc)
      • Generate Primary serial (OTA-989, uptane_serial_test.cc)
      • Use a provided hardware ID (uptane_test.cc)
      • Use the system hostname as hardware ID if one is not provided (uptane_init_test.cc)
        • Read the hostname from the system (utils_test.cc)
    • Register ECUs with Director
      • Register Primary ECU with Director (uptane_test.cc)
      • Register Secondary ECUs with Director (uptane_test.cc)
    • Abort if initialization fails
      • Recover from partial provisioning and network loss (OTA-991, uptane_network_test.cc, uptane_key_test.cc)
      • Detect and recover from failed provisioning (uptane_init_test.cc)
    • Verify Secondaries against storage
      • Identify previously unknown Secondaries (uptane_test.cc)
      • Identify currently unavailable Secondaries (uptane_test.cc)
  • Send system/network info to server
    • Read hardware info from the system (utils_test.cc)
    • Send hardware info to the server (OTA-984, uptane_test.cc)
    • Import a list of installed packages into the storage (uptane_test.cc)
      • Store a list of installed package versions (uptane_test.cc)
    • Send a list of installed packages to the server (OTA-984, uptane_test.cc)
    • Read networking info from the system (utils_test.cc)
    • Send networking info to the server (OTA-984, uptane_test.cc)
    • Generate and send manifest (see below)
    • Send SendDeviceDataComplete event (uptane_test.cc)
  • Check for campaigns
    • Check for campaigns with manual control (aktualizr_test.cc)
    • Fetch campaigns from the server (aktualizr_test.cc)
    • Parse campaigns from JSON (campaign_test.cc)
    • Send CampaignCheckComplete event with campaign data (aktualizr_test.cc)
  • Accept a campaign
    • Send campaign acceptance report
      • Send an event report (see below)
    • Send CampaignAcceptComplete event
  • Decline a campaign
    • Send campaign decline report
      • Send an event report (see below)
    • Send CampaignDeclineComplete event
  • Postpone a campaign
    • Send campaign postpone report
      • Send an event report (see below)
    • Send CampaignPostponeComplete event
  • Fetch metadata from server
    • Generate and send manifest (see below)
    • Fetch metadata from the Director (uptane_test.cc, uptane_vector_tests.cc)
    • Check metadata from the Director (uptane_test.cc, uptane_vector_tests.cc)
      • Validate Uptane metadata (see below)
    • Identify targets for known ECUs (uptane_test.cc, uptane_vector_tests.cc)
    • Ignore updates for unrecognized ECUs (uptane_test.cc uptane_vector_tests.cc)
    • Fetch metadata from the Image repo (uptane_test.cc, uptane_vector_tests.cc)
    • Check metadata from the Image repo (uptane_test.cc, uptane_vector_tests.cc)
      • Validate Uptane metadata (see below)
  • Check for updates
    • Check metadata from the Director (uptane_test.cc, uptane_vector_tests.cc)
      • Validate Uptane metadata (see below)
    • Identify updates for known ECUs (uptane_test.cc, uptane_vector_tests.cc)
    • Ignore updates for unrecognized ECUs (uptane_test.cc uptane_vector_tests.cc)
    • Check metadata from the Image repo (uptane_test.cc, uptane_vector_tests.cc)
      • Validate Uptane metadata (see below)
    • Send UpdateCheckComplete event with available updates (aktualizr_test.cc)
    • Send UpdateCheckComplete event after successful check with no available updates (aktualizr_test.cc)
    • Send UpdateCheckComplete event after failure (aktualizr_test.cc)
  • Pause and Resume the API
    • Suspend API calls during pause
    • Catch up with calls queue after resume
  • Download updates
    • Find requested target
      • Search first-order delegations (uptane_delegation_test.cc)
    • Download an update
      • Download an OSTree package (fetcher_test.cc)
      • Download a binary package (uptane_vector_tests.cc, aktualizr_test.cc)
      • Download from URI specified in target metadata (fetcher_test.cc)
      • Download from default file server URL (fetcher_test.cc)
      • Send EcuDownloadStartedReport to server (aktualizr_test.cc)
        • Send an event report (see below)
    • Report download progress (aktualizr_test.cc)
    • Pause downloading (fetcher_test.cc)
      • Pausing while paused is ignored (fetcher_test.cc)
      • Pausing while not downloading is ignored (fetcher_test.cc)
    • Resume downloading (fetcher_test.cc)
      • Resuming while not paused is ignored (fetcher_test.cc)
      • Resuming while not downloading is ignored (fetcher_test.cc)
      • Resume download interrupted by restart (fetcher_test.cc)
    • Verify a downloaded update
      • Verify an OSTree package (fetcher_test.cc)
      • Verify a binary package (uptane_vector_tests.cc, aktualizr_test.cc)
      • Send EcuDownloadCompletedReport to server (aktualizr_test.cc)
        • Send an event report (see below)
    • Send DownloadTargetComplete event if download is successful (aktualizr_test.cc)
    • Send DownloadTargetComplete event if download is unsuccessful (aktualizr_test.cc)
    • Send AllDownloadsComplete event after all downloads are finished (aktualizr_test.cc)
    • Send AllDownloadsComplete event after partial download success (aktualizr_test.cc)
    • Send AllDownloadsComplete event if there is nothing to download (aktualizr_test.cc)
    • Send AllDownloadsComplete event if all downloads are unsuccessful (aktualizr_test.cc)
  • Access downloaded binaries via API (aktualizr_test.cc)
    • List targets in storage via API (aktualizr_test.cc)
    • Remove targets in storage via API(aktualizr_test.cc)
  • Install updates
    • Send metadata to Secondary ECUs (uptane_test.cc)
    • Identify ECU for each target (uptane_test.cc, aktualizr_test.cc)
      • Reject targets which do not match a known ECU (uptane_test.cc)
    • Install updates on Primary
      • Check if there are updates to install for the Primary (uptane_test.cc, aktualizr_test.cc)
      • Check if an update is already installed (uptane_test.cc)
      • Set boot count to 0 and rollback flag to 0 to indicate system update
      • Send InstallStarted event for Primary (aktualizr_test.cc)
      • Send EcuInstallationStartedReport to server for Primary (uptane_test.cc, aktualizr_test.cc)
        • Send an event report (see below)
      • Install an update on the Primary
        • Install an OSTree update on the Primary (aktualizr_fullostree_test.cc)
        • Notify "reboot needed" after an OSTree update trigger
        • Set new version to pending status after an OSTree update trigger (aktualizr_test.cc)
        • Send EcuInstallationAppliedReport to server after an OSTree update trigger (aktualizr_test.cc)
        • Uptane check for updates and manifest sends are disabled while an installation is pending reboot (aktualizr_test.cc)
        • Trigger a system reboot at the end of the installation process in case of the OSTree package manager usage (OTA-2135)
        • Emulate a reboot at the end of the installation process in case of the fake package manager usage (OTA-2135, aktualizr_test.cc)
        • Install a binary update on the Primary (uptane_test.cc, aktualizr_test.cc)
      • Store installation result for Primary (uptane_test.cc)
      • Send InstallTargetComplete event for Primary (aktualizr_test.cc)
      • Send EcuInstallationCompletedReport to server for Primary (uptane_test.cc, aktualizr_test.cc)
        • Send an event report (see below)
    • Install updates on Secondaries
      • Send InstallStarted event for Secondaries (aktualizr_test.cc)
      • Send EcuInstallationStartedReport to server for Secondaries (uptane_test.cc)
        • Send an event report (see below)
      • Send images to Secondary ECUs (aktualizr_test.cc)
      • Store installation result for Secondary (aktualizr_test.cc)
      • Send InstallTargetComplete event for Secondaries (aktualizr_test.cc)
      • Send EcuInstallationCompletedReport to server for Secondaries (aktualizr_test.cc)
        • Send an event report (see below)
    • Store installation result for device (uptane_test.cc)
    • Compute device installation failure code as concatenation of ECU failure codes (aktualizr_test.cc)
    • Store negative device installation result when an ECU installation failed (aktualizr_test.cc)
    • Update is not in pending state anymore after failed installation (aktualizr_test.cc)
    • Send AllInstallsComplete event after all installations are finished (aktualizr_test.cc)
    • Automatically remove old targets during installation cycles (aktualizr_test.cc)
  • Send installation report
    • Generate and send manifest (see below)
    • Send PutManifestComplete event if send is successful (aktualizr_test.cc)
    • Send PutManifestComplete event if send is unsuccessful (uptane_test.cc)
    • Append custom installation report to the "custom" field of the manifest (aktualizr_test.cc)

Internal and common actions

These are internal requirements that are relatively opaque to the user and/or common to multiple external actions.

  • Validate Uptane metadata
    • Validate hashes
      • Validate SHA256 hashes (crypto_test.cc)
      • Validate SHA512 hashes (crypto_test.cc)
    • Sign and verify signatures
      • Sign and verify a file with RSA key stored in a file (crypto_test.cc)
      • Verify an ED25519 signature (crypto_test.cc)
      • Refuse to sign with an invalid key (crypto_test.cc)
      • Reject a signature if the key is invalid (crypto_test.cc)
      • Reject bad signatures (crypto_test.cc)
    • Sign TUF metadata
      • Sign TUF metadata with RSA2048 (keymanager_test.cc)
      • Sign TUF metadata with ED25519 (keymanager_test.cc)
    • Validate TUF roles (tuf_test.cc)
      • Delegated roles have custom names (tuf_test.cc)
      • Reject delegated role names that are identical to reserved role names (tuf_test.cc)
    • Validate Root metadata (tuf_test.cc, uptane_test.cc)
      • Throw an exception if Root metadata is invalid
        • Throw an exception if Root metadata is unsigned (tuf_test.cc, uptane_test.cc)
        • Throw an exception if Root metadata has no roles (tuf_test.cc)
        • Throw an exception if Root metadata has unknown signature types (uptane_test.cc)
        • Throw an exception if Root metadata has invalid key IDs (uptane_test.cc)
        • Throw an exception if Root metadata signature threshold is invalid (uptane_test.cc)
    • Parse Uptane timestamps (types_test.cc)
      • Throw an exception if an Uptane timestamp is invalid (types_test.cc)
      • Get current time (types_test.cc)
    • Validate first-order target delegations (uptane_delegation_test.cc)
    • Reject http GET responses that exceed size limit (httpclient_test.cc)
    • Reject http GET responses that do not meet speed limit (httpclient_test.cc)
    • Abort update if any signature threshold is <= 0 (REQ-153, uptane_vector_tests.cc)
    • Abort update if any metadata has expired (REQ-150, uptane_vector_tests.cc)
    • Abort update if a target hash is invalid (uptane_vector_tests.cc)
    • Abort update if any signature threshold is unmet (uptane_vector_tests.cc)
    • Abort update if any signatures are not unique (uptane_vector_tests.cc)
    • Abort update if any metadata is unsigned (uptane_vector_tests.cc)
    • Abort update if any metadata has an invalid key ID (uptane_vector_tests.cc)
    • Abort update if a target is smaller than stated in the metadata (uptane_vector_tests.cc)
    • Accept update with rotated Uptane roots (uptane_vector_tests.cc)
    • Abort update with incorrectly rotated Uptane roots (uptane_vector_tests.cc)
    • Abort update if any metadata has an invalid hardware ID (uptane_vector_tests.cc)
    • Abort update if the Director Targets metadata has an invalid ECU ID (uptane_vector_tests.cc)
    • Recover from an interrupted Uptane iteration (uptane_test.cc)
  • Generate and send manifest
    • Get manifest from Primary (uptane_test.cc)
      • Get Primary installation result (uptane_test.cc)
    • Get manifest from Secondaries (uptane_test.cc)
      • Ignore Secondaries with bad signatures (uptane_test.cc)
    • Send manifest to the server (uptane_test.cc)
  • Send an event report
    • Generate a random UUID (utils_test.cc)
    • Include correlation ID from Targets metadata (aktualizr_test.cc)
      • Correlation ID is empty if none was provided in Targets metadata (aktualizr_test.cc)
    • Report an event to the server (reportqueue_test.cc)
      • Report a series of events to the server (reportqueue_test.cc)
      • Recover from errors while sending event reports (reportqueue_test.cc)
  • Support OSTree as a package manager (packagemanagerfactory_test.cc)
    • Reject bad OSTree server URIs (ostreemanager_test.cc)
    • Abort if the OSTree sysroot is invalid (ostreemanager_test.cc)
    • Parse a provided list of installed packages (ostreemanager_test.cc)
    • Communicate with a remote OSTree server
      • Communicate with a remote OSTree server without credentials (ostreemanager_test.cc)
      • Communicate with a remote OSTree server with credentials (ostreemanager_test.cc)
  • Store state in an SQL database
    • Migrate forward through SQL schemas (sqlstorage_test.cc)
      • Automatically use latest SQL schema version when initializing database (sqlstorage_test.cc)
    • Migrate backward through SQL schemas (sqlstorage_test.cc)
    • Reject invalid SQL databases (sqlstorage_test.cc)
    • Migrate from the legacy filesystem storage (sqlstorage_test.cc, uptane_test.cc)
    • Load and store Primary keys in an SQL database (storage_common_test.cc)
    • Load and store TLS credentials in an SQL database (storage_common_test.cc)
    • Load and store Uptane metadata in an SQL database (storage_common_test.cc)
    • Load and store Uptane roots in an SQL database (storage_common_test.cc)
    • Load and store the device ID in an SQL database (storage_common_test.cc)
    • Load and store ECU serials in an SQL database (storage_common_test.cc)
      • Preserve ECU ordering between store and load calls (storage_common_test.cc)
    • Load and store a list of misconfigured ECUs in an SQL database (storage_common_test.cc)
    • Load and store a flag indicating successful registration in an SQL database (storage_common_test.cc)
    • Load and store an ecu installation result in an SQL database (storage_common_test.cc)
    • Load and store a device installation result in an SQL database (storage_common_test.cc)
    • Load and store targets in an SQL database (storage_common_test.cc)
    • Import keys and credentials from file into an SQL database (storage_common_test.cc)
  • Configuration
    • Parse config files in TOML format (config_test.cc)
    • Write config to file or to the log (config_test.cc)
    • Parse multiple config files in a directory (config_test.cc)
    • Parse multiple config files in multiple directories (config_test.cc)
  • Miscellaneous
    • Create a temporary file (utils_test.cc)
      • Write to a temporary file (utils_test.cc)
    • Create a temporary directory (utils_test.cc)
    • Serialize and deserialize asn1 (asn1_test.cc)
    • Support a fake package manager for testing (packagemanagerfactory_test.cc)
    • Support virtual partial verification Secondaries for testing
      • Partial verification Secondaries generate and store public keys (uptane_secondary_test.cc)
      • Partial verification Secondaries can verify Uptane metadata (uptane_secondary_test.cc)

Expected action sequences

This is just the list of sequences currently covered. It is likely that there are more worth testing, but these tests are expensive.

  • Initialize -> UptaneCycle -> no updates -> no further action or events (aktualizr_test.cc)
  • Initialize -> UptaneCycle -> updates downloaded and installed for Primary and Secondary (aktualizr_test.cc)
  • Initialize -> UptaneCycle -> updates downloaded and installed for Primary (after reboot) and Secondary (aktualizr_test.cc)
  • Initialize -> UptaneCycle -> updates downloaded and installed for Secondaries without changing the Primary (aktualizr_test.cc)
  • Initialize -> CheckUpdates -> no updates -> no further action or events (aktualizr_test.cc)
  • Initialize -> Download -> nothing to download (aktualizr_test.cc)
  • Initialize -> CheckUpdates -> Download -> updates downloaded but not installed (aktualizr_test.cc)
  • Initialize -> Install -> nothing to install (aktualizr_test.cc)
  • Initialize -> CheckUpdates -> Download -> Install -> updates installed (aktualizr_test.cc)
  • Provision with shared credentials with real server. Initialize -> CheckUpdates -> verify state with aktualizr-info (shared_cred_prov_test.py)
  • 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)
  • 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

These tools all link with libaktualizr, although they do not necessary use the API.

aktualizr-primary

aktualizr-primary is the reference user of the libaktualizr API. Note that for historical reasons, it is usually simply known as aktualizr. It is a thin layer around libaktualizr. This is just the list of things currently tested that relate specifically to it.

  • Abort when given bogus command line options (tests/CMakeLists.txt)
  • Abort when given a nonexistant config file (tests/CMakeLists.txt)
  • Support debug logging (tests/CMakeLists.txt)
  • Default to informational logging (tests/CMakeLists.txt)

aktualizr-secondary

aktualizr-secondary was designed to demonstrate an Uptane-compliant Secondary but is currently not part of the core product. It also uses libaktualizr, but less extensively than aktualizr-primary. This is just the list of things currently tested that relate specifically to it.

  • Parse config files in TOML format (aktualizr_secondary_config_test.cc)

  • Write its config to file or to the log (aktualizr_secondary_config_test.cc)

  • Generate a serial (aktualizr_secondary/uptane_test.cc)

  • Generate a hardware ID (aktualizr_secondary/uptane_test.cc)

  • Generate keys (aktualizr_secondary/uptane_test.cc)

  • Extract credentials from a provided archive (aktualizr_secondary/uptane_test.cc)

  • Abort when given bogus command line options (aktualizr_secondary/CMakeLists.txt)

  • Abort when given a nonexistant config file (aktualizr_secondary/CMakeLists.txt)

  • Support debug logging (aktualizr_secondary/CMakeLists.txt)

  • Default to informational logging (aktualizr_secondary/CMakeLists.txt)

aktualizr-info

aktualizr-info provides information about libaktualizr's state to a developer with access to a device.

  • Parse libaktualizr configuration files (see Configuration section above)
    • Parse config files in TOML format (aktualizr_info_config_test.cc)
    • Write its config to file or to the log (aktualizr_info_config_test.cc)
  • Print information from libaktualizr storage (aktualizr_info_test.cc)
    • Print device ID (aktualizr_info_test.cc)
    • Print Primary ECU serial (aktualizr_info_test.cc)
    • Print Primary ECU hardware ID (aktualizr_info_test.cc)
    • Print Secondary ECU serials (aktualizr_info_test.cc)
    • Print Secondary ECU hardware IDs (aktualizr_info_test.cc)
    • Print Secondary ECUs no longer accessible (miscofigured: old) (aktualizr_info_test.cc)
    • Print Secondary ECUs registered after provisioning (not registered) (aktualizr_info_test.cc)
    • Print provisioning status (aktualizr_info_test.cc)
    • Print whether metadata has been fetched from the server (aktualizr_info_test.cc)
    • Print Root metadata from Image repository (aktualizr_info_test.cc)
    • Print Targets metadata from Image repository (aktualizr_info_test.cc)
    • Print Root metadata from Director repository (aktualizr_info_test.cc)
    • Print Targets metadata from Director repository (aktualizr_info_test.cc)
    • Print TLS credentials (aktualizr_info_test.cc)
    • Print Primary ECU keys (aktualizr_info_test.cc)
    • Print Primary ECU current and pending versions (aktualizr_info_test.cc)
    • Print Secondary ECU current and pending versions (aktualizr_info_test.cc)
    • Print device name only for scripting purposes (aktualizr_info_test.cc)
    • Print delegations (aktualizr_info_test.cc)
    • Print Snapshot metadata (aktualizr_info_test.cc)
    • Print Timestamp metadata (aktualizr_info_test.cc)

uptane-generator

uptane-generator is used in testing to simulate the generation of Uptane repositories.

  • Generate Image and Director repos (repo_test.cc)
  • Add an image to the Image repo (repo_test.cc)
    • Add custom image metadata without an actual file (repo_test.cc)
  • Copy an image to the Director repo (repo_test.cc)
    • Clear the staged Director Targets metadata (repo_test.cc)
    • Populate the Director Targets metadata with the currently signed metadata (repo_test.cc)
  • Sign Director repo Targets metadata (repo_test.cc)
  • Add simple delegation (repo_test.cc)
  • Add image with delegation (repo_test.cc)
  • Sign arbitrary metadata (repo_test.cc)

aktualizr-cert-provider

aktualizr-cert-provider assists with generating credentials and uploading them to a device for device credential provisioning.

  • Use file paths from config if provided (cert_provider_test.cc)
  • Use shared provisioning credentials if fleet CA and private key are not provided (cert_provider_shared_cred_test.cc)
    • Generate a random device ID (OTA-986, utils_test.cc, uptane_init_test.cc)
    • Provision with shared credentials (cert_provider_shared_cred_test.cc)
  • Use fleet credentials if provided (cert_provider_test.cc)
    • Abort if fleet CA is provided without fleet private key (cert_provider_test.cc)
    • Abort if fleet private key is provided without fleet CA (cert_provider_test.cc)
    • Specify RSA bit length (cert_provider_test.cc)
    • Specify device certificate expiration date (cert_provider_test.cc)
    • Specify device certificate country code (cert_provider_test.cc)
    • Specify device certificate state abbreviation (cert_provider_test.cc)
    • Specify device certificate organization name (cert_provider_test.cc)
    • Specify device certificate common name (cert_provider_test.cc)
    • Read fleet CA certificate (cert_provider_test.cc)
    • Read fleet private key (cert_provider_test.cc)
    • Create device certificate (cert_provider_test.cc)
    • Create device keys (cert_provider_test.cc)
    • Set public key for the device certificate (cert_provider_test.cc)
    • Sign device certificate with fleet private key (cert_provider_test.cc)
    • Serialize device private key to a string (cert_provider_test.cc)
    • Serialize device certificate to a string (cert_provider_test.cc)
  • Read server root CA from p12 in the credentials archive (cert_provider_shared_cred_test.cc)
  • Write credentials to a local directory if requested (cert_provider_test.cc)
    • Provide device private key (cert_provider_test.cc)
    • Provide device certificate (cert_provider_test.cc)
    • Provide root CA if requested (cert_provider_shared_cred_test.cc)
    • Provide server URL if requested (cert_provider_shared_cred_test.cc)
  • Copy credentials to a device with ssh (covered by oe-selftest)
    • Create parent directories
    • Provide device private key
    • Provide device certificate
    • Provide root CA if requested
    • Provide server URL if requested

Garage (sota) tools

These tools also use libaktualizr, but only for common utility functions. They are focused specifically on dealing with OSTree objects. They originally lived in a separate repo, which is where the "sota_tools" name came from. The garage nomenclature refers to the historical name of our reference SaaS server, ATS Garage, before it was renamed HERE OTA Connect.

garage-push

garage-push pushes OSTree objects to a remote Treehub server.

  • Verify a local OSTree repository (ostree_dir_repo_test.cc)
    • Reject invalid path (ostree_dir_repo_test.cc)
    • Reject invalid repo configuration (ostree_dir_repo_test.cc)
    • Reject bare mode repo (ostree_dir_repo_test.cc)
  • Parse credentials (see below)
  • Parse OSTree ref or commit refhash (sota_tools/CMakeLists.txt, test-dry-run)
    • Find OSTree commit object in local repository (see below)
    • Generate an OSTree hash from a commit ref (see below)
  • Authenticate with treehub server (see below)
  • Fetch OSTree objects from source repository and push to destination repository (see below)
  • Check if credentials support offline signing (authenticate_test.cc)
  • Upload root ref to Image repository if credentials do not support offline signing
  • Abort when given bogus command line options (sota_tools/CMakeLists.txt, test-bad-option)
  • Support debug logging (sota_tools/CMakeLists.txt, test-verbose-logging)

garage-deploy

garage-deploy moves OSTree objects from one remote Treehub server to another.

  • Parse credentials for destination server (see below)
  • Parse credentials for source server (see below)
  • Authenticate with source server (see below)
  • Generate an OSTree hash from a commit ref (see below)
  • Fetch OSTree objects from source repository and push to destination repository (see below)
    • Abort if commit is not present in source server (sota_tools/CMakeLists.txt, test-missing-commit)
  • Check if credentials support offline signing (authenticate_test.cc)
    • Abort if credentials do not support offline signing (sota_tools/CMakeLists.txt, test-garage-deploy-online-signing)
  • Use garage-sign to offline sign targets for destination repository (sota_tools/CMakeLists.txt, test-garage-deploy-offline-signing)
    • Do not reuse lingering credentials from previous runs of garage-sign
    • Remove local tuf repo generated by garage-sign after use (sota_tools/CMakeLists.txt, test-garage-deploy-offline-signing)
  • Abort when given bogus command line options (sota_tools/CMakeLists.txt, test-bad-option)
  • Support debug logging (sota_tools/CMakeLists.txt)
  • Support trace logging (sota_tools/CMakeLists.txt)

garage-check

garage-check simply verifies that a given OSTree commit exists on a remote Treehub server and is present in the targets.json from the Image repository.

  • Parse credentials (see below)
  • Authenticate with treehub server (see below)
  • Verify that a commit exists in a remote repo (sota_tools/CMakeLists.txt, run_expired_test.sh)
  • Get targets.json from Image repository (sota_tools/CMakeLists.txt, run_expired_test.sh)
    • Abort if targets.json has expired (sota_tools/CMakeLists.txt, run_expired_test.sh)
  • Find specified OSTree ref in targets.json (sota_tools/CMakeLists.txt, run_expired_test.sh)

Internal and common actions

  • Parse credentials
    • Reject a bogus provided file (authenticate_test.cc)
      • Abort when given nonexistent credentials (sota_tools/CMakeLists.txt, test-missing-credentials)
      • Abort when given bogus credentials (sota_tools/CMakeLists.txt, test-invalid-credentials, test-garage-deploy-missing-fetch-credentials, test-garage-deploy-missing-push-credentials)
    • Extract credentials from a provided archive (authenticate_test.cc)
      • Reject a provided archive file without a treehub.json (authenticate_test.cc)
      • Reject a provided archive file with bogus credentials (authenticate_test.cc)
    • Extract credentials from a provided JSON file (authenticate_test.cc)
      • Reject a bogus provided JSON file (authenticate_test.cc)
    • Parse authentication information from treehub.json (authenticate_test.cc)
    • Parse Image repository URL from a provided archive (authenticate_test.cc)
    • Parse treehub URL from a provided archive
  • Authenticate with treehub server
    • Authenticate with username and password (basic auth) (treehub_server_test.cc)
    • Authenticate with OAuth2 (treehub_server_test.cc, authenticate_test.cc)
    • Authenticate with TLS credentials (authenticate_test.cc)
    • Authenticate with nothing (no auth) (authenticate_test.cc)
    • Use a provided CA certificate (sota_tools/CMakeLists.txt, test-cacert-used)
      • Abort when given a bogus CA certificate (sota_tools/CMakeLists.txt, test-cacert-not-found)
    • Abort if authorization fails (sota_tools/CMakeLists.txt, test-auth-plus-failure)
    • Abort if destination server is unavailable (sota_tools/CMakeLists.txt, test-garage-deploy-upload-failed)
  • Generate an OSTree hash from a ref string
    • Generate an OSTree hash from a ref string (ostree_hash_test.cc)
    • Ignore case of OSTree ref strings (ostree_hash_test.cc)
    • Reject empty OSTree ref strings (ostree_hash_test.cc)
    • Reject bogus OSTree ref strings (ostree_hash_test.cc)
  • Fetch OSTree objects from source repository and push to destination repository (deploy_test.cc)
    • Get OSTree commit object in source repository (see below)
    • Query destination repository for OSTree commit object (see below)
    • Parse OSTree object to identify child objects (deploy_test.cc)
    • Query destination repository for child objects recursively (see below)
    • Get child objects from source repository recursively (see below)
    • Upload missing OSTree objects to destination repository (ostree_object_test.cc)
      • Detect curl misconfiguration (ostree_object_test.cc)
      • Skip upload if dry run was specified (ostree_object_test.cc)
        • Support dry run with local repos (sota_tools/CMakeLists.txt, test-garage-deploy-dry-run)
        • Support dry run with auth plus using a real server (sota_tools/CMakeLists.txt, test-dry-run)
      • Upload objects concurrently (rate_controller_test.cc)
        • Initial rate controller status is good (rate_controller_test.cc)
        • Rate controller aborts if it detects server or network failure (rate_controller_test.cc)
        • Rate controller continues through intermittent errors (rate_controller_test.cc)
        • Rate controller improves concurrency when network conditions are good (rate_controller_test.cc)
      • Recover from the server hanging on to connections (sota_tools/CMakeLists.txt, test-server-500)
      • Recover from intermittent errors (sota_tools/CMakeLists.txt, test-server-error_every_10)
      • Abort when server becomes unresponsive (sota_tools/CMakeLists.txt, test-server-500_after_20)
  • Get OSTree object from a repository
    • Find OSTree object in local repository (ostree_dir_repo_test.cc)
      • Check all valid OSTree object extensions (ostree_dir_repo_test.cc)
      • Abort if OSTree object is not found (ostree_dir_repo_test.cc)
        • Abort when given a bogus OSTree ref (sota_tools/CMakeLists.txt, test-missing-ref)
    • Fetch OSTree object from remote repository (ostree_http_repo.cc)
      • Check all valid OSTree object extensions (ostree_http_repo.cc)
      • Retry fetch if not found after first try (ostree_http_repo.cc)
      • Abort if OSTree object is not found after retry (ostree_http_repo.cc)
  • Query destination repository for OSTree object (ostree_object_test.cc)
    • Expect HTTP 200 for a hash that we expect the server to know about (ostree_object_test.cc)
    • Expect HTTP 404 for a hash that we expect the server not to know about (ostree_object_test.cc)

meta-updater

meta-updater is a Yocto layer used to build aktualizr, garage-push, OSTree, and other related tools.

  • Run garage-push
  • Run garage-deploy
  • Run garage-sign
  • Build credentials into an image
  • Run aktualizr-cert-provider
  • Build an image with shared credential provisioning that provisions successfully
  • Build an image with device credential provisioning that provisions successfully
  • Build an image with device credential provisioning using an HSM that provisions successfully
  • Build an image with manual control that provisions successfully
  • Build an image for Raspberry Pi
  • Build an image using grub as a bootloader that provisions successfully
  • Build an image for a Secondary
  • Build an image for a Primary intended to connect to a Secondary