xref: /aosp_15_r20/bootable/libbootloader/gbl/docs/gbl_efi_avb_protocol.md (revision 5225e6b173e52d2efc6bcf950c27374fd72adabc) 
1# GBL AVB EFI Protocol
2
3This protocol delegates some of AVB-related logic to the firmware, including
4tasks such as verifying public keys, handling verification results, and
5managing the device’s secure state (e.g., ROT, lock state, rollback indexes,
6etc.).
7
8## GBL_EFI_AVB_PROTOCOL
9
10### GUID
11```c
12// {6bc66b9a-d5c9-4c02-9da9-50af198d912c}
13#define GBL_EFI_AVB_PROTOCOL_UUID                    \
14  {                                                  \
15    0x6bc66b9a, 0xd5c9, 0x4c02, {                    \
16      0x9d, 0xa9, 0x50, 0xaf, 0x19, 0x8d, 0x91, 0x2c \
17    }                                                \
18  }
19```
20
21### Revision Number
22
23Note: revision 0 means the protocol is not yet stable and may change in
24backwards-incompatible ways.
25
26```c
27#define GBL_EFI_AVB_PROTOCOL_REVISION 0x00010000
28```
29
30### Protocol Interface Structure
31
32```c
33typedef struct _GBL_EFI_AVB_PROTOCOL {
34  UINT64 Revision;
35  GBL_EFI_AVB_VALIDATE_VBMETA_PUBLIC_KEY ValidateVbmetaPublicKey;
36  GBL_EFI_AVB_READ_IS_DEVICE_UNLOCKED ReadIsDeviceUnlocked;
37  GBL_EFI_AVB_READ_ROLLBACK_INDEX ReadRollbackIndex;
38  GBL_EFI_AVB_WRITE_ROLLBACK_INDEX WriteRollbackIndex;
39  GBL_EFI_AVB_READ_PERSISTENT_VALUE ReadPersistentValue;
40  GBL_EFI_AVB_WRITE_PERSISTENT_VALUE WritePersistentValue;
41  GBL_EFI_AVB_HANDLE_VERIFICATION_RESULT HandleVerificationResult;
42} GBL_EFI_AVB_PROTOCOL;
43```
44
45### Parameters
46
47#### Revision
48The revision to which the `GBL_EFI_AVB_PROTOCOL` adheres. All
49future revisions must be backwards compatible. If a future version is not
50backwards compatible, a different GUID must be used.
51
52#### ValidateVbmetaPublicKey
53Validate proper public key is used to sign HLOS artifacts.
54[`ValidateVbmetaPublicKey()`](#ValidateVbmetaPublicKey).
55
56#### ReadIsDeviceUnlocked
57Gets whether the device is unlocked.
58[`ReadIsDeviceUnlocked()`](#ReadIsDeviceUnlocked).
59
60#### ReadRollbackIndex
61Gets the rollback index corresponding to the location given by `index_location`.
62[`ReadRollbackIndex()`](#ReadRollbackIndex).
63
64#### WriteRollbackIndex
65Sets the rollback index corresponding to the location given by `index_location` to `rollback_index`.
66[`WriteRollbackIndex()`](#WriteRollbackIndex).
67
68#### ReadPersistentValue
69Gets the persistent value for the corresponding `name`.
70[`ReadPersistentValue()`](#ReadPersistentValue).
71
72#### WritePersistentValue
73Sets or erases the persistent value for the corresponding `name`.
74[`WritePersistentValue()`](#WritePersistentValue).
75
76#### HandleVerificationResult
77Handle AVB verification result (i.e update ROT, set device state, display UI
78warnings/errors, handle anti-tampering, etc).
79[`HandleVerificationResult()`](#HandleVerificationResult).
80
81TODO(b/337846185): Cover more AVB functionality such as rollback indexes, open dice, etc.
82TODO(b/337846185): Detailed (per-method) doc once protocol is finalized.
83
84### Status Codes Returned
85
86The following EFI error types are used to communicate result to GBL and libavb in particular:
87
88|                                |                                                                                                                                                         |
89| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
90| `EFI_SUCCESS`                  | Requested operation was successful `libavb::AvbIOResult::AVB_IO_RESULT_OK`                                                                              |
91| `EFI_STATUS_OUT_OF_RESOURCES`  | Unable to allocate memory `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_OOM`                                                                                |
92| `EFI_STATUS_DEVICE_ERROR`      | Underlying hardware (disk or other subsystem) encountered an I/O error `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_IO`                                    |
93| `EFI_STATUS_NOT_FOUND`         | Named persistent value does not exist `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_NO_SUCH_VALUE`                                                          |
94| `EFI_STATUS_END_OF_FILE`       | Range of bytes requested to be read or written is outside the range of the partition `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION` |
95| `EFI_STATUS_INVALID_PARAMETER` | Named persistent value size is not supported or does not match the expected size `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE`          |
96| `EFI_STATUS_BUFFER_TOO_SMALL`  | Buffer is too small for the requested operation `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE`                                           |
97| `EFI_STATUS_UNSUPPORTED`       | Operation isn't implemented / supported                                                                                                                 |
98