SecureBoot Monitor Mode

The BL1 platform implementation includes a UART monitor to facilitate secure provisioning and de-brick support of firmware, key provision as well as other functions.

Following are the high-level features of the Monitor Mode:

The monitor mode can be entered as using the strapping pins on either LAN966x or LAN969x.
The protocol supports code download over RS232 and USB (serial device mode only).
The protocol is resilient to transmission errors
The protocol has data integrity checks.
The protocol can authenticate downloaded code, using necessary certificates, digests, and OTP_TBBR_ROTPK in OTP (as TF-A normally authenticates BL2).

The monitor is intended to be used as a stepping stone for more complicated features.

The SoC will act as a server, and a client will be connected by the RS232 or USB cable.

If downloaded code is executed, it is entered in the same manner as the BL1 executes a normal BL2 image, but using the BL2U image ID. If code is not authenticated/executed, the normal boot process can be resumed under client control.

1. Monitor Mode Protocol

This section describes a protocol that provides the features described in the previous section.

1.1. Base Protocol Data Unit

The protocol is by default only using printable ASCII characters, but data payload can use binary (i.e. no) encoding.

The protocol format is defined by:

A Start-Of-Frame indicator '>'
A single-character command type:
- 'V' - GET VERSION REQUEST
- 'S' - SEND DATA REQUEST
- 'D' - DATA CHUNK REQUEST
- 'U' - AUTHENTICATE REQUEST
- 'O' - OVERRIDE STRAPPING REQUEST
- 'C' - CONTINUE BOOT REQUEST
- 'T' - TRACE LOG-LEVEL
- 'P' - PROGRAM OTP ADDRESS
- 'R' - PROGRAM OTP ADDRESS WITH RANDOM DATA
- 'M' - COMMIT OTP EMULATION DATA
- 'G' - WRITE OTP REGIONS
- 'Q' - SJTAG READ CHALLENGE
- 'A' - SJTAG WRITE RESPONSE
- 'a' - ACK (response)
- 'n' - NACK (response)
A single-character delimiter ','
A general-purpose command argument - 32 bits encoded as 8 hexadecimal characters.
A single-character delimiter ','
A payload length field - 32 bits encoded as 8 hexadecimal characters.
A single-character payload delimiter - '#' used for hex encoding or '%' when no encoding (binary) is used.
The payload data - encoded as 2 hexadecimal characters per bytes of data when encoding is used. This may be null if the payload length is zero.
CRC32c of the full PDU, excluding the SOF indicator. 32 bits encoded as 8 hexadecimal characters.

The payload encoding format is decided by the transmitter, the receiver must be capable of decoding both formats. The server must start operation in encoded format.

1.1.1. PDU reference

SOF

'>'

Command

1 character

delimiter

','

Arg

8 hex digits

delimiter

','

Payload len

8 hex digits

delimiter

'#' or '%'

Payload

2 hex digits per payload byte (maybe empty)

CRC

8 hex digits

1.1.2. PDU examples

The examples here are presented with the SOF marker, and a newline at the end. The newline is purely presentational here, but it should be noted that anything after the CRC part and until the SOF marker should be discarded by the PDU reception process (at either side).

>V,00000000,00000000#8bda80cb
>a,00000000,00000018#56657273696f6e20312e33204d616e6963204d616e746973fb025b81
>V,00000000,00000000%ad7b6723
>a,00000000,00000018%Version 1.3 Manic Mantisaa2ca8d3
>S,00004169,00000000#98DED8A3
>n,00000000,00000000#ba356a97
>D,000000a0,00000020#0623134302D0302102F056EB0020606010BD00BFC8451000F0B50C4687B018B996CDB78C
>a,00000000,00000000#751AA63B

1.2. Protocol exchanges

These simple diagrams describe the PDU flows.

All exchanges are initiated from the client - which is in the following diagrams assumed on the right, the server on the left.

All instances of "ACK" also represent a possible "NACK" in case of failure.

1.2.1. Get Version

The client might need to identify the firmware version.

               <<<<< "GET VERSION REQUEST"
                     "ACK+payload" >>>>

Example:

REQ: >V,00000000,00000000#8bda80cb
RSP: >a,00000000,00000018#56657273696f6e20312e33204d616e6963204d616e746973fb025b81

1.2.2. Download code

The client needs to download code to perform hardware operations.

The "SEND DATA REQUEST" defines the total length of download. If ACK’ed, data transfer can be initiated.

The individual "DATA CHUNK REQUEST" units will contain download offset and payload. Data must be downloaded sequentially. Data chucks are ACK/NACK’ed individually in order for re-transmission to be possible. The client dictates the individual chunk size (greater than 0).

The ACK/NACK PDU.arg field will match corresponding the DATA PDU field.

               <<<<< "SEND DATA REQUEST"
                     "ACK" >>>>
               <<<<< "DATA DOWLOAD CHUNK #0000"
                     "ACK" >>>>
               <<<<< "DATA DOWLOAD CHUNK #0001"
                     "ACK" >>>>
               ....

Example (encoded and binary, same data):

REQ: >S,00000010,00000000#50e77db2
RSP: >a,00000000,00000000#810d67bd
REQ: >D,00000000,00000008#30313238343536377c2d3fb4
RSP: >a,00000000,00000000#810d67bd
REQ: >D,00000008,00000008#383961626364656631341093
RSP: >a,00000008,00000000#2d330271
REQ: >S,00000010,00000000%76469a5a
RSP: >a,00000000,00000000%a7ac8055
REQ: >D,00000000,00000008%01284567d8ba385d
RSP: >a,00000000,00000000%a7ac8055
REQ: >D,00000008,00000008%89abcdefe6968b93
RSP: >a,00000008,00000000%0b92e599

1.2.3. State diagram

It is worth noting that the "DATA REQUEST" PDU is only accepted after the "SEND REQUEST", and only until all data has been received. The following state diagram illustrates this.

1.2.4. Authenticate code

The client needs to authenticate downloaded code in order to execute it.

The authentication operates on the FWU_FIP that typically have been downloaded to SRAM first.

The FWU_FIP must contain the BL2U image as well as certificates to authenticate it. If no ROTPK is deployed, authentication is skipped, but still SHA digests in the certificate are checked to guarantee data integrity. The trusted FWU certificate use the same ROTPK but a different key and thus a different certificate than the normal BL2/trusted firmware.

The FWU_FIP may contain other elements as well, but notice that the SRAM download area is restricted to about 80K.

The FWU_FIP may also be placed direcly into storage media as well, using external tools. The strappings must be reset (physically or overridden) to elect the proper storage media before issuing the AUTHENTICATE command if the FIP should be collected from the storage media as opposed to a downloaded FWU_FIP.

If the authentication succeeds, the BL2U is immediately executed.

Note: The loading of the BL2U image from the SRAM FIP may destructively overwrite the SRAM FIP while copying the image. This is by design, and can be seen as a relocation of the BL2U image. As certificates are read first as part of the authentication and used to verify the image before execution, there is no data corruption possible. And since the BL2U will execute after authentication, the SRAM FIP is no longer of use.

               <<<<< "AUTHENTICATE REQUEST"
                     "ACK" >>>>

Example:

REQ: >U,00000000,00000000#d21e980c
RSP: >a,00000000,00000000#810d67bd

1.2.5. Override strapping

The client may need to override the device strapping, before normal boot is resumed.

It is only possible to use the following values for strapping override:

3: MMC
4: QSPI
5: SD card
6: PCIE endpoint

The command will provide a strapping value that will override the actual device strapping while continuing normal boot ("CONTINUE BOOT REQUEST").

When this request is ACK’ed, the override strapping is in effect.

               <<<<< "OVERRIDE STRAPPING REQUEST"
                     "ACK" >>>>

Example:

REQ: >O,00000003,00000000#c51f321e
RSP: >a,00000000,00000000#810d67bd

1.2.6. Continue boot

The client may need to continue the normal boot process.

When this request is ACK’ed, the system will continue the normal operation.

               <<<<< "CONTINUE BOOT REQUEST"
                     "ACK" >>>>

Example:

REQ: >C,00000000,00000000#1b9d4941
RSP: >a,00000000,00000000#810d67bd

1.2.7. Read Secure JTAG challenge

TODO

1.2.8. Write Secure JTAG response to open op device

Payload

nil

TF-A uses the following defines:

#define LOG_LEVEL_NONE       U(0)
#define LOG_LEVEL_ERROR      U(10)
#define LOG_LEVEL_NOTICE     U(20)
#define LOG_LEVEL_WARNING    U(30)
#define LOG_LEVEL_INFO       U(40)
#define LOG_LEVEL_VERBOSE    U(50)

1.3.9. Program OTP

Sent by client.

Command

'P'

Arg

OTP Address to program (byte address)

Payload

Value to program

Notice if this command is used to program an already programmed address, then the effect will be a logical OR of the provided value and the existing values. Some OTP address has HW protection to avoid this. In other cases this is the desired behaviour (setting more bits in a mask).

A maximum length of 1024 data bytes is allowed in one request.

1.3.10. Program OTP with secure random generated values

Sent by client.

Command

'R'

Arg

OTP Address to program (byte address)

Payload

4 bytes length, encoded as a network-order (be) 32 bit integer.

Similar to 'P', but value is secure random generated. This is useful to program the HUK.

A maximum length of 1024 data bytes is allowed in one request.

1.3.11. Program OTP with data from OTP emulation layer

Sent by client.

Command

'M'

Arg

0 (not used)

Payload

nil

This will commit any data from the OTP emulation layer to the OTP HW.

1.3.12. Program OTP with OTP region definitions

Sent by client.

Command

'G'

Arg

0 (not used)

Payload

nil

This will write the OTP regions to the device should this not already be programmed. The OTP regions are normally written during chip production, so this command is only needed in rare circumstances.

1.3.13. ACK

Sent by server.

Command

'a'

Arg

Depends on request type

Payload

Depends on request type

1.3.14. NACK

Sent by server.

Command

'n'

Arg

Depends on request type

Payload

(Possible) error cause text