Packaging tasks

Packaging tasks are the automated and user-friendly way to produce secured firmware and software artifacts in a container format. The packaging flow is asynchronous, event-driven and involves multiple internal and external services. It must reference the device configuration that shall be used as it provides information about the encryption key.

Generally speaking, the packaging procedure can be split in three steps:

1. Uploading one or more firmware files and one or more metadata files.

2. Triggering the packaging step e.g. creating a packaging task.

3. The packaging task will in turn execute encryption and signing tasks and package the results according to a specification (cf. S&E Default packaging for the default format, if no custom specific format is provided).

The packaging procedure usually involves two personas - the product owner and the firmware developer. The product owner is the one who has access rights to create the initial device configuration and allows releases for the firmware developer. While the firmware developer would trigger the packaging task, the product owner has to approve it, before it is executed.

All tasks go through the same flow with the following possible task statuses:

Once the packaging task completes and has status DONE, the container can be downloaded and deployed in the field. The result of the task is also communicated as an event and tracked in the audit log.

As mentioned, a packaging task triggers the separate signing and encryption tasks and for this reason it is useful to be aware of the flow of the other two types of tasks, depicted in the next chapters.

The following information is also useful if you want to achieve a different flow customized for your use case.

Encryption tasks

Here is the happy path of an encryption task:

1. The firmware developer sends a POST request with the file to the API endpoint on the server side. This request must contain all the necessary information e.g. what kind of key should be used, what kind of file will be encrypted.

2. An encryption task is then created and the developer immediately receives a response containing its Id. The developer does not receive the encrypted file yet. The Sign & Encrypt service maintains a state for this task e.g. CREATED.

3. Internal work on the encrypting then starts (executed in a dedicated environment, which is split network-wise). This work includes:

   1. scheduling the task

   2. dispatching an encryption command (if needed, encryption could be done via an external service such as KMS on AWS)

4. Once the encryption is completed, the information where the file can be retrieved from is also passed and the state of the task is set to DONE.

5. When using the API, the firmware developer has to manually check whether the task has completed.

6. As soon as the task state is set to DONE, the firmware developer should send another GET request to download the encrypted file. The result will contain a URL from a Bosch IoT Rollouts proxy or a free link. The result has a time limit, so if you are trying to access the file after the specific limit it might point to a non-existing file.

   When using the Sign & Encrypt UI you are notified when the task is done, the download starts automatically and you will receive an indication if the file is not available anymore.

Signing tasks

The signing flow introduces the requirement of an approval, which is also part of the packaging task flow. In contrast to the encryption task where the product owner has no interaction with the process, here once the task is created, it is waiting until the product owner approves it and only then the actual encryption commences.

1. The firmware developer sends a POST request with the file to the API endpoint on the server side.

2. A signing task is created and the developer immediately receives a response with the Id and the status for this task, which in this case will be WAITING.

3. The product owner has to approve the task via another POST request, and once its status is set to APPROVED, the signing task is dispatched to the signing service.

4. Once the signing is completed, its status is set to DONE.

5. When using the API, the user has to manually check whether the task has completed and once its status is DONE, he or she will receive the outcome as a string.