Device Management Client 3.2.0

Note: If you are using Device Management Client 3.2.0, we recommend that you upgrade to 3.3.0 (or later) as soon as possible. In 3.2.0, if an SSL session is stored when the device rebootstraps, a bootstrap loop may render the device unusable. Client 3.3.0 release fixes this issue by clearing the SSL session.

Features

• Implemented support for compressed delta updates.
  • This feature can reduce the size of firmware update images as the image will have only the changed parts rather than the full image.
• Implemented SSL session resume.
  • This feature reduces the need for full handshakes (and thus amount of data transferred and time used for reconnections) as long as the session is valid.
  • Session information is stored in the configured secure storage, so consider the potential flash wearing.
  • To minimize flash wearing, session information is only stored when it changes.

Device Management Client example

• Updated to Mbed OS 5.12.4.
• Added delta tool to the example application.

Factory Configurator Client example

• Updated to Mbed OS 5.12.4.
• [Linux] network Ethernet interface information is available in the ETHERNET_LINUX_IFACE_NAME environment variable.

Device Management Connect client

• Relaxed the enforcement of client configuration. Only SN_COAP_MAX_BLOCKWISE_SIZE is considered as a mandatory application configuration due to bootstrap and update (CoAP download) dependencies.
  • LIFETIME (default 3600 seconds), ENDPOINT_TYPE ("default") and TRANSPORT_MODE (default TCP) now have defaults. The application does not need to define them if default values are acceptable.
• Added new public APIs to the MbedCloudClient class to request Enrollment over Secure Transport (EST) (est_request_enrollment) and free the resulting certificate chain context (est_free_cert_chain_context).

Device Management Update client

• Added the delta update feature into Update client.
• Fixed HTTP download for very small files.
• Implemented a check to reject zero bytes firmware.
• Fixed installation authorization logic which was proceeding without waiting for the application callback.
• Fixed manifest manager to report correct error codes.
• Fixed PAL include files.
• Optimized flash and RAM footprint for CoAP source.
• Added a check to ensure that SN_COAP_MAX_BLOCKWISE_PAYLOAD_SIZE is aligned with the storage page size.
• Added code to read the active firmware metadata header from file. This enables e-2-e testing with filesystem storage in a Linux host.
• Added heap and stack statistic trace messages.

Factory configurator client

• Naming restrictions for KCM APIs are now identical for KVStore and Pelion Secure Storage solutions (ESFS-SOTP):
  • kcm_item_name must only include characters a-z, A-Z, 0-9, _, -, ..
  • The max kcm_item_name length is 100 bytes.
  • This deprecates Pelion Secure Storage naming restrictions.
• New APIs:
  • kcm_asymmetric_sign computes ECDSA raw signature on hash digest using associated private key name. Supports keys with EC SECP256R1 curve only.
  • kcm_asymmetric_verify verifies ECDSA raw signature on hash digest using associated private key name. Supports keys with EC SECP256R1 curve only.
  • kcm_generate_random generates a random number into a given buffer.
  • kcm_ecdh_key_agreement computes a shared secret using the elliptic curve Diffie Hellman algorithm.
• Fixed a bug in conversion of private key from DER to raw.
• kcm_item_close_handle receives a pointer to the handle instead of the handle. This is a bugfix for crash when kcm_item_close_handle is called twice.

Platform Adaptation Layer (PAL)

New cryptographic APIs implemented for PSA and non-PSA variants:

• pal_parseECPrivateKeyFromHandle parses EC private key from PAL private key handle.
• pal_parseECPublicKeyFromHandle parses EC public key from PAL public key handle.
• pal_asymmetricSign computes ECDSA raw signature of a previously hashed message. Supports keys with EC SECP256R1 curve only.
• pal_asymmetricVerify verifies the ECDSA raw signature of a previously hashed message. Supports keys with EC SECP256R1 curve only.
• pal_ECDHKeyAgreement computes raw shared secret key using elliptic curve Diffie–Hellman algorithm.

Other changes:

• Fixed unnessary dependencies to SN_COAP_MAX_BLOCKWISE_SIZE parameter.
• Added pal_x509CertCheckExtendedKeyUsage that checks the usage of certificate against extended-key-usage extension.
• [Linux] When creating threads, use the system provided PTHREAD_STACK_MIN as a minimum value. Previously, the application was allowed to define values smaller than the system-defined minimum.
• Implemented SSL session resume feature. This feature is enabled by default. Use the PAL_USE_SSL_SESSION_RESUME flag to control it.

Yocto changes

• Removed the dependency of requiring Mbed CLI to be globally installed. This allows also virtualenv installations of Mbed CLI to work with the provided meta-layers.
  • Changed the meta-layer to use SSH authentication for Mbed CLI when needed. This is mostly needed when pulling in meta-layers from private repositories.
  • Changed the meta-mbed-cloud-client.lib file to use https format instead of ssh.

Delta update related:

• Modified application makefiles to call the new script for building a tar package of rootfs.
• Added the build-raspberry-update-rootfs-tar.sh script for building a tar package of rootfs contents to be used for delta purposes.
• Edited the local configuration sample and fstab to set rootfs into "read-only" mode so that delta firmware update can be applied into the device.
• Edited the Update client metalayer recipe to include the Prepare script in the image for delta processing.

Known issues

• [PAL tests] PAL filesystem and PAL update tests currently support external SD card as storage. Support for other storages will be added in future release.
• Delta update feature requires manifest-tool version 1.5.0 or later. If used with Mbed OS version 5.12 or earlier, the Mbed CLI tool may downgrade the manifest-tool to an earlier version not supporting delta features.

Mbed OS

We recommend that you read the Mbed OS release notes for known issues and their latest status.

• PSA is in preview level and as such not ready for production yet.
  • You cannot update the pre-compiled PSA binary through firmware update. You can only update the application itself.
  • Cypress PSoC6:
    • Issues with storage. Random failures can occur in testing.
    • The native Wi-Fi driver is feature-rich and as such it is quite large (400 KB) and with PSA included (220 KB) there is not much space for the OS and application.
    • Client has been tested with ESP8266 (due to flash size) without flow control, because flow-control does not work with this board yet. ESP8266 without flow-control will not work reliably.
  • NXP LPC55S69:
    • The board has only 640 KB flash. PSA takes 192 KB out of it.
    • You can use the Client example (with firmware update and bootloader) with release profile due to the flash size limitation.
    • Only ARMC6 is supported for compilation.
  • K64F:
    • You can use the board in PSA mode (without real HW PSA implementation).
    • The configuration file that allows this is placed under configs-psa folder in the example.
    • The PSA mode adds RAM consumption (static +3.5 KB) and flash/ROM consumption (+18.5 KB).
    • Arm and partners are optimizing the solution in future releases.

Linux

• Firmware update installation for very large images on Raspberry Pi3B or Pi3B+ may fail with mmc0 timeout failure. This is a generic Raspberry Pi3 issue, see RPI issue #2392.
• Firmware update from one Linux distribution version to another does not work. For example, firmware update from Yocto distribution Morty to Rocko is not currently possible, as there are Linux version-dependent files (device tree) in the BOOT partition. Therefore, you must update within one major version of a distribution.
• glibc versions 2.23 and 2.24 have a bug in thread creation. It can cause random crashes with Linux.
  • If possible, update glibc to version 2.25 (or later). See sourceware issue 20116 for details.
  • We have implemented a workaround for this issue to decrease its likelihood. This issue may still occur under certain circumstances.
• The Device Management Client application must run as root to have access rights to perform the firmware update.
  • This is not the most secure way to handle this issue, so a more secure implementation will come later.
• Yocto distribution has only been tested in developer certificate mode.

Device Management Client 3.2.0 Third Party IP report

Device Management Client uses some open source third-party IP (TPIP). This table lists the TPIP and sources:

You also get more TPIP with the Mbed OS release itself, see their LICENSE.md for details.

Device Management Client example

• Updated to Mbed OS 5.12.2.
• Fixed the application initialization issue in production flow. This fixes a regression caused by 3.1.0 release.
• Fixed a compilation issue of Nucleo F429ZI board with the root-level mbed_app.json.

Known issues

Older versions of Device Management SDK for Python (v2.03 or older) sent PUT payload with content type JSON, which is an unsupported content type for Client. Client version 2.2.1 no longer accepts PUT requests with unsupported data types. We recommend that you update to SDK v2.0.5 or later, which sends the requests with correct content type (text/plain).

Mbed OS

We recommend that you read the Mbed OS release notes for known issues and their latest status.

• In UDP mode, bootstrap fails with smallest SSL fragment length.
• PSA is in preview level and as such not ready for production yet.
  • You cannot update the pre-compiled PSA binary through firmware update. You can only update the application itself.
  • Cypress PSoC6:
    • Issues with storage. Random failures can occur in testing.
    • The native Wi-Fi driver is feature-rich and as such it is quite large (400 KB) and with PSA included (220 KB) there is not much space for the OS and application.
    • Client has been tested with ESP8266 (due to flash size) without flow control, because flow-control does not work with this board yet. ESP8266 without flow-control will not work reliably.
  • NXP LPC55S69:
    • The board has only 640 KB flash. PSA takes 192 KB out of it.
    • You can use the Client example (with firmware update and bootloader) with release profile due to the flash size limitation.
    • Only ARMC6 is supported for compilation.
  • K64F:
    • You can use the board in PSA mode (without real HW PSA implementation).
    • The configuration file that allows this is placed under configs-psa folder in the example.
    • The PSA mode adds RAM consumption (static +3.5 KB) and flash/ROM consumption (+18.5 KB).
    • Arm and partners are optimizing the solution in future releases.

Linux

• Firmware update installation for very large images on Raspberry Pi3B or Pi3B+ may fail with mmc0 timeout failure. This is a generic Raspberry Pi3 issue, see RPI issue #2392.
• Firmware update from one Linux distribution version to another does not work. For example, firmware update from Yocto distribution Morty to Rocko is not currently possible, as there are Linux version-dependent files (device tree) in the BOOT partition. Therefore, you must update within one major version of a distribution.
• glibc versions 2.23 and 2.24 have a bug in thread creation. It can cause random crashes with Linux.
  • If possible, update glibc to version 2.25 (or newer). See sourceware issue 20116 for details.
  • We have implemented a workaround for this issue to decrease its likelihood. This issue may still occur under certain circumstances.
• The Device Management Client application must run as root to have access rights to perform the firmware update.
  • This is not the most secure way to handle this issue, so a more secure implementation will come later.
• Yocto distribution has only been tested in developer certificate mode.

Device Management 3.1 Client Third Party IP report

Device Management Client uses some open source third-party IP (TPIP). This table lists the TPIP and sources:

You also get more TPIP with the Mbed OS release itself, see their LICENSE.md for details.