[v6,8/8] docs: k3: Add secure booting documentation

This commit adds a general flow to explain the usage of firewalls and
the chain of trust in K3 devices.

Signed-off-by: Manorit Chawdhry <m-chawdhry@ti.com>
---
 doc/board/ti/k3.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

On 12/6/23 3:51 AM, Manorit Chawdhry wrote:
> This commit adds a general flow to explain the usage of firewalls and
> the chain of trust in K3 devices.
> 
> Signed-off-by: Manorit Chawdhry <m-chawdhry@ti.com>
> ---
>   doc/board/ti/k3.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 45 insertions(+)
> 
> diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
> index 947b86ba8292..60d04c5708be 100644
> --- a/doc/board/ti/k3.rst
> +++ b/doc/board/ti/k3.rst
> @@ -104,6 +104,51 @@ firmware can be loaded on the now free core in the wakeup domain.
>   For more information on the bootup process of your SoC, consult the
>   device specific boot flow documentation.
>   
> +Secure Boot
> +^^^^^^^^^^^
> +
> +K3 HS-SE devices are used for authenticated boot flow with secure boot.

How about:

K3 HS-SE devices enforce an authenticated boot flow for secure boot.

> +HS-FS devices have optional authentication in the flow and doesn't "require"
> +authentication unless converted to HS-SE devices.

HS-FS is the state of a K3 device before it has been eFused with
customer security keys. In the HS-FS state the authentication still
can function as in HS-SE but as there are no customer keys to verify
the signatures against the authentication will pass for certificates
signed with any key.

> +
> +Chain of trust
> +""""""""""""""
> +
> +1) SMS starts up and loads the authenticated ROM code in Wakeup Domain
> +2) ROM code starts up and loads the authenticated tiboot3.bin in Wakeup
> +   Domain
> +3) Wakeup SPL (tiboot3.bin) would authenticate the next set of binaries
> +   (ATF,OP-TEE,DM,SPL,etc.)
> +4) After ATF and OP-TEE load, ARMV8 U-boot authenticates the next set of
> +   binaries (Linux and DTBs) if using FIT Image authentication and having a
> +   signature node in U-boot.


This might be better said like this:

1) Public ROM loads the tiboot3.bin (R5 SPL, TIFS)
2) R5 SPL loads tispl.bin (ATF, OP-TEE, DM, SPL)
3) SPL loads u-boot.img (U-Boot)
4) U-Boot loads fitImage (Linux and DTBs)

Each stage authenticating (and optionally decrypting) while loading is
implied by the following sentences below, no need to repeat each time.

Plus the use of "ROM" is confusing, we have two ROMs in K3 (Secure ROM
and Public ROM), you should always be specific.

> +
> +Steps 1-3 are all authenticated by either the ROM code or TIFS as the

s/ROM code/Secure ROM

> +authenticating entity and step 4 uses U-boot standard mechanism for
> +authenticating.
> +
> +All the authentication that are done for ROM/TIFS are done through x509
> +certificates that are signed.
> +
> +Firewalls
> +"""""""""
> +
> +1) ROM comes up and sets up firewalls that are needed by itself

Secure ROM

> +2) TIFS (in multicertificate will setup it's own firewalls)

TIFS sets up it's own firewalls in either case.

> +3) R5 SPL comes along and opens up other firewalls ( that are not owned by
> +   anyone - essentially firewalls that were setup by ROM but are not needed
> +   anymore)

How about:

3) R5 SPL will remove any firewalls that are leftover from the Secure ROM stage
that are no longer required.

> +4) Each stage beyond this: such as tispl.bin containing TFA/OPTEE uses OIDs to
> +   set up firewalls to protect themselves (enforced by TIFS)
> +5) TFA/OP-TEE can configure other firewalls at runtime if required as they
> +   are already authenticated and firewalled off from illegal access.
> +6) A53 SPL and U-boot itself startups but has no ability to change the
> +   protection firewalls enforced by x509 OIDs or any other firewalls
> +   configured by ROM/TIFS in the beginning.

6) All later stages can setup or remove firewalls that have not been already
configured by previous stages, such as those created by TIFS, TFA, and OP-TEE.

> +
> +Futhur, firewalls have a lockdown bit in hardware that enforces the setting
> +(and cannot be over-ridden) till the full system is resetted.

s/till/until
s/resetted/reset

Andrew

> +
>   Software Sources
>   ----------------
>   
>

Hi Andrew,

On 10:41-20231206, Andrew Davis wrote:
> On 12/6/23 3:51 AM, Manorit Chawdhry wrote:
> > This commit adds a general flow to explain the usage of firewalls and
> > the chain of trust in K3 devices.
> > 
> > Signed-off-by: Manorit Chawdhry <m-chawdhry@ti.com>
> > ---
> >   doc/board/ti/k3.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++
> >   1 file changed, 45 insertions(+)
> > 
> > diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
> > index 947b86ba8292..60d04c5708be 100644
> > --- a/doc/board/ti/k3.rst
> > +++ b/doc/board/ti/k3.rst
> > @@ -104,6 +104,51 @@ firmware can be loaded on the now free core in the wakeup domain.
> >   For more information on the bootup process of your SoC, consult the
> >   device specific boot flow documentation.
> > +Secure Boot
> > +^^^^^^^^^^^
> > +
> > +K3 HS-SE devices are used for authenticated boot flow with secure boot.
> 
> How about:
> 
> K3 HS-SE devices enforce an authenticated boot flow for secure boot.
> 
> > +HS-FS devices have optional authentication in the flow and doesn't "require"
> > +authentication unless converted to HS-SE devices.
> 
> HS-FS is the state of a K3 device before it has been eFused with
> customer security keys. In the HS-FS state the authentication still
> can function as in HS-SE but as there are no customer keys to verify
> the signatures against the authentication will pass for certificates
> signed with any key.
> 
> > +
> > +Chain of trust
> > +""""""""""""""
> > +
> > +1) SMS starts up and loads the authenticated ROM code in Wakeup Domain
> > +2) ROM code starts up and loads the authenticated tiboot3.bin in Wakeup
> > +   Domain
> > +3) Wakeup SPL (tiboot3.bin) would authenticate the next set of binaries
> > +   (ATF,OP-TEE,DM,SPL,etc.)
> > +4) After ATF and OP-TEE load, ARMV8 U-boot authenticates the next set of
> > +   binaries (Linux and DTBs) if using FIT Image authentication and having a
> > +   signature node in U-boot.
> 
> 
> This might be better said like this:
> 
> 1) Public ROM loads the tiboot3.bin (R5 SPL, TIFS)
> 2) R5 SPL loads tispl.bin (ATF, OP-TEE, DM, SPL)
> 3) SPL loads u-boot.img (U-Boot)
> 4) U-Boot loads fitImage (Linux and DTBs)
> 
> Each stage authenticating (and optionally decrypting) while loading is
> implied by the following sentences below, no need to repeat each time.
> 
> Plus the use of "ROM" is confusing, we have two ROMs in K3 (Secure ROM
> and Public ROM), you should always be specific.
> 
> > +
> > +Steps 1-3 are all authenticated by either the ROM code or TIFS as the
> 
> s/ROM code/Secure ROM
> 
> > +authenticating entity and step 4 uses U-boot standard mechanism for
> > +authenticating.
> > +
> > +All the authentication that are done for ROM/TIFS are done through x509
> > +certificates that are signed.
> > +
> > +Firewalls
> > +"""""""""
> > +
> > +1) ROM comes up and sets up firewalls that are needed by itself
> 
> Secure ROM
> 
> > +2) TIFS (in multicertificate will setup it's own firewalls)
> 
> TIFS sets up it's own firewalls in either case.
> 
> > +3) R5 SPL comes along and opens up other firewalls ( that are not owned by
> > +   anyone - essentially firewalls that were setup by ROM but are not needed
> > +   anymore)
> 
> How about:
> 
> 3) R5 SPL will remove any firewalls that are leftover from the Secure ROM stage
> that are no longer required.
> 
> > +4) Each stage beyond this: such as tispl.bin containing TFA/OPTEE uses OIDs to
> > +   set up firewalls to protect themselves (enforced by TIFS)
> > +5) TFA/OP-TEE can configure other firewalls at runtime if required as they
> > +   are already authenticated and firewalled off from illegal access.
> > +6) A53 SPL and U-boot itself startups but has no ability to change the
> > +   protection firewalls enforced by x509 OIDs or any other firewalls
> > +   configured by ROM/TIFS in the beginning.
> 
> 6) All later stages can setup or remove firewalls that have not been already
> configured by previous stages, such as those created by TIFS, TFA, and OP-TEE.
> 
> > +
> > +Futhur, firewalls have a lockdown bit in hardware that enforces the setting
> > +(and cannot be over-ridden) till the full system is resetted.
> 
> s/till/until
> s/resetted/reset
> 

Have incorporated the suggested changes, Thanks!

Regards,
Manorit

> Andrew
> 
> > +
> >   Software Sources
> >   ----------------
> >