
.. _sec-mcuboot-oad-types:

OAD Storage & Security
======================

There are a couple of aspects with OAD that one must take into account when
choosing which type of OAD implementation suits your application.

One aspect is where a new downloaded image is to be stored during the OAD
process, for which you have three methods: on-chip, off-chip, dual-image. On-chip OAD
and dual-image OAD both store the downloaded image to internal flash, while off-chip OAD stores the
downloaded image to external flash.

Another aspect is security, which is to whether or not authenticate a new
downloaded image to be from a trusted source. This OAD solution uses MCUBoot,
hence, it is not possible to do OAD without security. Secure OAD authenticates
new images using an Elliptic Curve Digital Signature Algorithm (:term:`ECDSA`)
before it is executed on-chip.

.. _sec-mcuboot-oad-types-storage:

OAD Storage
-----------

.. ifconfig:: device == 'cc23xx'

    During an OAD procedure the candidate image is stored either in the internal
    flash when using On-chip OAD or Dual-image OAD, or in external flash when using
    off-chip OAD. On-chip, dual-image and off-chip OAD have associated trade-offs and benefits,
    which are summarized in the "OAD storage comparison" table below.

    The biggest advantage of using on-chip OAD and dual-image OAD is allowing a single-chip OAD
    solution. However, on-chip OAD and dual-image OAD both put restrictions on application size in
    terms of flash usage.

.. ifconfig:: device != 'cc23xx'
    
    During an OAD procedure the candidate image is stored either in the internal
    flash, which is called on-chip OAD, or in external flash, which is called
    off-chip OAD. On-chip and off-chip OAD has associated trade-offs and benefits,
    which are summarized in the "OAD storage comparison" table below.

    The biggest advantage of using on-chip OAD is allowing a single-chip OAD
    solution. However, on-chip OAD does put restrictions on application size in
    terms of flash usage.

Off-chip OAD does not have these restrictions, and can store multiple
application images and a factory image in the external flash without limiting
the application size on the internal flash. This, of course, comes at the cost
of requiring an additional component.

Despite their differences, the different OAD types are invariant to the
transport of candidate images.

.. ifconfig:: device == 'cc23xx'

    .. table:: OAD method comparison

        +--------------+-----------------------------------+---------------------------------+
        | Method       | Advantages                        | Limitations                     |
        +==============+===================================+=================================+
        | On-chip      | - No external flash required      | - Application size restriction  |
        |              | - Download is performed by        | - Persistent application is     |
        |              |   persistent application leaving  |   required.                     |
        |              |   more flash for incoming image.  |                                 |
        +--------------+-----------------------------------+---------------------------------+
        | Off-chip     | - Ability to store multiple /     | - Low power external flash      |
        |              |   backup images                   |   required                      |
        |              | - App + Stack merged update       |                                 |
        |              |   supported                       |                                 |
        |              | - Maximum application size        |                                 |
        |              |   available to customer           |                                 |
        +--------------+-----------------------------------+---------------------------------+
        | Dual-Image   | - No external flash required      | - Application size restriction  |
        +--------------+-----------------------------------+---------------------------------+

.. ifconfig:: device != 'cc23xx'

    .. table:: OAD method comparison

        +--------------+-----------------------------------+---------------------------------+
        | Method       | Advantages                        | Limitations                     |
        +==============+===================================+=================================+
        | On-chip      | - No external flash required      | - Application size restriction  |
        |              | - Download is performed by        | - Persistent application is     |
        |              |   persistent application leaving  |   required.                     |
        |              |   more flash for incoming image.  |                                 |
        +--------------+-----------------------------------+---------------------------------+
        | Off-chip     | - Ability to store multiple /     | - Low power external flash      |
        |              |   backup images                   |   required                      |
        |              | - App + Stack merged update       |                                 |
        |              |   supported                       |                                 |
        |              | - Maximum application size        |                                 |
        |              |   available to customer           |                                 |
        +--------------+-----------------------------------+---------------------------------+

.. _sec-mcuboot-oad-types-security:

OAD Security
------------

When talking about security in the context of OAD, it is referred to whether
or not new downloaded images must be authenticated as part of the OAD process.
It does not refer to the security level of the actual transport mechanism of
the OAD image. The main purpose for authenticating new downloaded images is to
verify the image is from an entrusted source. Secure OAD will always
authenticate new images as part of the OAD process when properly implemented
along with the secure bootloader.

Secure OAD uses Elliptic Curve Digital Signature Algorithm (:term:`ECDSA`) to
sign and verify secure OAD images. More specifically, the ECDSA-P256 algorithm
is implemented. The underlying authentication mechanisms for :term:`ECDSA` is
that a suitable private and public key pair are generated, and that the
private key used for image signing is thoroughly protected. Only the public
key is stored on Target device.

.. warning::

    It is imperative that the system developer protect the corresponding
    private key. Since any party that has access to the private key can
    generate signed images, these images will be treated as a valid authentic
    image and executed by the device. Likewise, if the private key is lost,
    the ability to generate new valid firmware images is lost.
