1# GBL AVB EFI Protocol 2 3## GBL_EFI_AVB_PROTOCOL 4 5### Summary 6 7This protocol allows to delegate device-specific Android verified booot (AVB) 8logic to the firmware. 9 10`GBL_EFI_AVB_PROTOCOL` protocol isn't required for dev GBL flavour with 11intention to support basic Android boot functionality on dev boards. On the 12production devices this protocol must be provided by the FW to ensure HLOS 13integrity. 14 15### GUID 16```c 17// {6bc66b9a-d5c9-4c02-9da9-50af198d912c} 18#define GBL_EFI_AVB_PROTOCOL_UUID \ 19 { \ 20 0x6bc66b9a, 0xd5c9, 0x4c02, { \ 21 0x9d, 0xa9, 0x50, 0xaf, 0x19, 0x8d, 0x91, 0x2c \ 22 } \ 23 } 24``` 25 26### Revision Number 27 28Note: revision 0 means the protocol is not yet stable and may change in 29backwards-incompatible ways. 30 31```c 32#define GBL_EFI_AVB_PROTOCOL_REVISION 0x00010000 33``` 34 35### Protocol Interface Structure 36 37```c 38typedef struct _GBL_EFI_AVB_PROTOCOL { 39 UINT64 Revision; 40 GBL_EFI_AVB_VALIDATE_VBMETA_PUBLIC_KEY ValidateVbmetaPublicKey; 41 GBL_EFI_AVB_READ_IS_DEVICE_UNLOCKED ReadIsDeviceUnlocked; 42 GBL_EFI_AVB_READ_ROLLBACK_INDEX ReadRollbackIndex; 43 GBL_EFI_AVB_WRITE_ROLLBACK_INDEX WriteRollbackIndex; 44 GBL_EFI_AVB_READ_PERSISTENT_VALUE ReadPersistentValue; 45 GBL_EFI_AVB_WRITE_PERSISTENT_VALUE WritePersistentValue; 46 GBL_EFI_AVB_HANDLE_VERIFICATION_RESULT HandleVerificationResult; 47} GBL_EFI_AVB_PROTOCOL; 48``` 49 50### Parameters 51 52#### Revision 53The revision to which the `GBL_EFI_AVB_PROTOCOL` adheres. All 54future revisions must be backwards compatible. If a future version is not 55backwards compatible, a different GUID must be used. 56 57#### ValidateVbmetaPublicKey 58Validate proper public key is used to sign HLOS artifacts. 59[`ValidateVbmetaPublicKey()`](#ValidateVbmetaPublicKey). 60 61#### ReadIsDeviceUnlocked 62Gets whether the device is unlocked. 63[`ReadIsDeviceUnlocked()`](#ReadIsDeviceUnlocked). 64 65#### ReadRollbackIndex 66Gets the rollback index corresponding to the location given by `index_location`. 67[`ReadRollbackIndex()`](#ReadRollbackIndex). 68 69#### WriteRollbackIndex 70Sets the rollback index corresponding to the location given by `index_location` to `rollback_index`. 71[`WriteRollbackIndex()`](#WriteRollbackIndex). 72 73#### ReadPersistentValue 74Gets the persistent value for the corresponding `name`. 75[`ReadPersistentValue()`](#ReadPersistentValue). 76 77#### WritePersistentValue 78Sets or erases the persistent value for the corresponding `name`. 79[`WritePersistentValue()`](#WritePersistentValue). 80 81#### HandleVerificationResult 82Handle AVB verification result (i.e update ROT, set device state, display UI 83warnings/errors, handle anti-tampering, etc). 84[`HandleVerificationResult()`](#HandleVerificationResult). 85 86## GBL_EFI_AVB_PROTOCOL.ValidateVbmetaPublicKey() {#ValidateVbmetaPublicKey} 87 88### Summary 89 90Allows the firmware to check whether the public key used to sign the `vbmeta` 91partition is trusted by verifying it against the hardware-trusted key shipped 92with the device. 93 94### Prototype 95 96```c 97typedef 98EFI_STATUS 99(EFIAPI *GBL_EFI_AVB_VALIDATE_VBMETA_PUBLIC_KEY) ( 100 IN GBL_EFI_AVB_PROTOCOL *This, 101 IN CONST UINT8 *PublicKeyData, 102 IN UINTN PublicKeyLength, 103 IN CONST UINT8 *PublicKeyMetadata, 104 IN UINTN PublicKeyMetadataLength, 105 /* GBL_EFI_AVB_KEY_VALIDATION_STATUS */ OUT UINT32 *ValidationStatus); 106``` 107 108### Parameters 109 110#### This 111A pointer to the `GBL_EFI_AVB_PROTOCOL` instance. 112 113#### PublicKeyData 114A pointer to the public key extracted from `vbmeta`. Guaranteed to contain valid 115data of length `PublicKeyLength`. 116 117#### PublicKeyLength 118Specifies the length of the public key provided by `PublicKeyData`. 119 120#### PublicKeyMetadata 121A pointer to public key metadata generated using the `avbtool` `--public_key_metadata` 122flag. May be `NULL` if no public key metadata is provided. 123 124#### PublicKeyMetadataLength 125Specifies the length of the public key metadata provided by `PublicKeyMetadata`. 126Guaranteed to be 0 in case of `NULL` `PublicKeyMetadata`. 127 128#### ValidationStatus 129An output parameter that communicates the verification status to the GBL. `VALID` 130and `VALID_CUSTOM_KEY` are interpreted as successful validation statuses. 131 132### Related Definition 133 134```c 135// Vbmeta key validation status. 136// 137// https://source.android.com/docs/security/features/verifiedboot/boot-flow#locked-devices-with-custom-root-of-trust 138typedef enum { 139 VALID, 140 VALID_CUSTOM_KEY, 141 INVALID, 142} GBL_EFI_AVB_KEY_VALIDATION_STATUS; 143``` 144 145### Description 146 147`ValidateVbmetaPublicKey` must set `ValidationStatus` and return `EFI_SUCCESS`. 148Any non `EFI_SUCCESS` return value from this method is treated as a fatal verification 149error, so `red` state is reported and GBL fails to boot even if device is unlocked. 150 151**`ValidationStatus` and GBL boot flow**: 152 153* `VALID`: The public key is valid and trusted, so the device can continue the boot 154 process for both locked and unlocked states. 155 156* `VALID_CUSTOM_KEY`: The public key is valid but not fully trusted. GBL continues 157 booting a locked device with a `yellow` state and an unlocked device with an `orange` state. 158 159* `INVALID`: The public key is not valid. The device cannot continue the boot process 160 for locked devices; GBL reports a `red` status and resets. Unlocked devices can still 161 boot with an `orange` state. 162 163GBL calls this function once per AVB verification session. 164 165## GBL_EFI_AVB_PROTOCOL.ReadIsDeviceUnlocked() {#ReadIsDeviceUnlocked} 166 167### Summary 168 169Allows the firmware to provide the device's locking state to the GBL in a 170firmware-specific way. 171 172### Prototype 173 174```c 175typedef 176EFI_STATUS 177(EFIAPI *GBL_EFI_AVB_READ_IS_DEVICE_UNLOCKED) ( 178 IN GBL_EFI_AVB_PROTOCOL *This, 179 OUT BOOLEAN *IsUnlocked); 180``` 181 182### Parameters 183 184#### This 185A pointer to the `GBL_EFI_AVB_PROTOCOL` instance. 186 187#### IsUnlocked 188An output parameter that communicates the device locking state to the GBL. 189 190### Description 191 192An unlocked device state allows GBL not to force AVB and to boot the device with 193an `orange` boot state. GBL rejects continuing the boot process if this method 194returns any error. GBL may call this method multiple times per boot session. 195 196## Status Codes Returned 197 198The following EFI error types are used to communicate result to GBL and libavb in particular: 199 200| | | 201| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | 202| `EFI_SUCCESS` | Requested operation was successful `libavb::AvbIOResult::AVB_IO_RESULT_OK` | 203| `EFI_STATUS_OUT_OF_RESOURCES` | Unable to allocate memory `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_OOM` | 204| `EFI_STATUS_DEVICE_ERROR` | Underlying hardware (disk or other subsystem) encountered an I/O error `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_IO` | 205| `EFI_STATUS_NOT_FOUND` | Named persistent value does not exist `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_NO_SUCH_VALUE` | 206| `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` | 207| `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` | 208| `EFI_STATUS_BUFFER_TOO_SMALL` | Buffer is too small for the requested operation `libavb::AvbIOResult::AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE` | 209| `EFI_STATUS_UNSUPPORTED` | Operation isn't implemented / supported | 210 211TODO(b/337846185): Provide docs for all methods.