Skip to content

Software Update Validation

Jump to bottom
Daniel Adam edited this page Jun 13, 2023 · 1 revision

Version: 2.2.5.6

Software Update (SWU) validation is a crucial step in ensuring the integrity and correctness of update payloads. The validation process automatically takes place when a payload, represented by an oc_rep_t structure, is loaded into the runtime representation of the /oc/swu resource. This occurs in two scenarios:

  1. Device Startup: Validation occurs when data is loaded from permanent data storage.

    • On Failure: The resource is set to default values.

  2. Update via CoAP POST Request: Validation is triggered when an update is received through a CoAP POST request.

    • On Failure: The resource remains unmodified, and a response with the code OC_STATUS_NOT_ACCEPTABLE is sent.

Validation on Demand

The SWU component's public API has been expanded to provide users with the ability to manually verify their data. The following additions have been made:

typedef enum {
  OC_SWUPDATE_VALIDATE_UPDATE_ERROR_INVALID_IMPLEMENTATION,
  OC_SWUPDATE_VALIDATE_UPDATE_ERROR_INVALID_PROPERTY,
  OC_SWUPDATE_VALIDATE_UPDATE_ERROR_READONLY_PROPERTY,
  OC_SWUPDATE_VALIDATE_UPDATE_ERROR_INVALID_PROPERTY_VALUE,
  OC_SWUPDATE_VALIDATE_UPDATE_ERROR_UPDATETIME_NOT_SET,
  OC_SWUPDATE_VALIDATE_UPDATE_ERROR_UPDATETIME_INVALID,
  OC_SWUPDATE_VALIDATE_UPDATE_ERROR_PURL_NOT_SET,
  OC_SWUPDATE_VALIDATE_UPDATE_ERROR_PURL_INVALID,
} oc_swupdate_validate_update_error_t;

typedef bool (*oc_swupdate_on_validate_update_error_fn_t)(const oc_rep_t *rep, oc_swupdate_validate_update_error_t error, void *data);

bool oc_swupdate_validate_update(size_t device, const oc_rep_t *rep, oc_swupdate_on_validate_update_error_fn_t on_error, void *data);

With these additions, users can now manually verify their data and examine any encountered errors in detail. The on_error callback is invoked when an error is detected during validation. The arguments passed to the callback depend on the specific error encountered. The return value of the callback determines whether the validation should continue (true) or end (false). This allows callers to examine all errors present in the payload thoroughly.

Detailed Description of on_error Invocations Based on the error Value:

  • OC_SWUPDATE_VALIDATE_UPDATE_ERROR_INVALID_IMPLEMENTATION: When this error occurs, rep is NULL. It indicates that SWU callbacks are not set (oc_swupdate_set_impl was not called) or that validate_purl is NULL.
  • OC_SWUPDATE_VALIDATE_UPDATE_ERROR_READONLY_PROPERTY: When this error occurs, rep is set to the currently examined property. It signifies that the payload contains a property defined as read-only by the OCF specification.
  • OC_SWUPDATE_VALIDATE_UPDATE_ERROR_INVALID_PROPERTY: When this error occurs, rep is set to the currently examined property. It indicates an invalid property name or type. For example, if the payload contains a power property that is not defined on the SWU resource or if a property defined by the specification has an invalid type (e.g., updatetime expected to be of string type).
  • OC_SWUPDATE_VALIDATE_UPDATE_ERROR_INVALID_PROPERTY_VALUE: When this error occurs, rep is set to the currently examined property. It indicates a valid property with an invalid value. For instance, if updatetime contains a string that is not a valid RFC3339 timestamp.
  • OC_SWUPDATE_VALIDATE_UPDATE_ERROR_UPDATETIME_NOT_SET: When this error occurs, rep is NULL. It means that the required updatetime property is missing from the payload.
  • OC_SWUPDATE_VALIDATE_UPDATE_ERROR_UPDATETIME_INVALID: When this error occurs, repis NULL, and it signifies that the absolute time parsed from the updatetime property is in the past.
  • OC_SWUPDATE_VALIDATE_UPDATE_ERROR_PURL_NOT_SET: When this error occurs, rep is NULL, indicating that the required purl property is not present in the payload.
  • OC_SWUPDATE_VALIDATE_UPDATE_ERROR_PURL_INVALID: When this error occurs, rep is NULL, indicating that the value of the purl property has failed validation by the validate_purl callback.

Special Values for the updatetime Property

The updatetime property is expected to contain a string representing a valid RFC3339 timestamp. Additionally, two special values are allowed:

  • "now": When encountering this value, the updatetime property is set to the current time at the moment of processing. This results in the immediate execution of the update action after the POST request processing is completed.
  • "none": When encountering this value, the updatetime property is set to a time value of 0. This modification of the SWU resource indicates that the update action is not executed, even though the resource itself is modified.

Special Values for the purl Property

The purl property is expected to be present in every request and is validated using the validate_purl callback. However, in the case where the purl property has been validly set previously and a new request is received with the purl value set to an empty string, the value of the purl property on the resource is not modified, and the validation by validate_purl is skipped.

By utilizing the extended API and understanding the different error scenarios, users can effectively validate their SWU payloads and ensure the integrity of the software update process.

Clone this wiki locally