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

[Manorit Chawdhry]

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 at 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
> >   ----------------
> >