Protected Confirmation implementation Stay organized with collections Save and categorize content based on your preferences.

Key Point: Protected Confirmation provides a guarantee that the user has read and confirmed a transaction. This guarantee relies on proper implementation. The considerations described in this section help to ensure a secure implementation. Review the device architecture with respect to these guarantees, even under the premise that the bootloader may be unlocked and a custom Android image installed.

Considerations

The following considerations must be addressed to ensure the integrity of Android Protected Confirmation. If these considerations can't be satisfactorily addressed, Protected Confirmation can't be implemented on the device.

Linux kernel considerations

Protected Confirmation is designed to operate securely even if the device's kernel is compromised. While the Protected Confirmation dialog is active, the kernel can't interfere with the integrity of the screen content, the integrity of the user's input, and the atomicity between user input and output. Architecturally, the kernel must be prevented from augmenting the user's decision and from spoofing user events in the first place. The kernel isn't considered trustworthy for this use case, as it could be under the control of an attacker or replaced with something completely different.

Firmware considerations

Protected Confirmation can be implemented on a device only if all of the components involved have trusted firmware. Protected Confirmation is designed to ensure that the user has a chance to read a message displayed in the Trusted UI to make an informed decision whether or not to proceed with a transaction. The display panel driver is especially important as this could prevent the user from being able to view the Trusted UI.

Input considerations

Choose a secure input method to ensure that input events generated by this chosen input method aren't conveyed to the Protected Confirmation dialog unless the user generates the event while that dialog is active.

Physical hardware

Any component that can be controlled by the Android kernel, such as the system on chip (SoC) or power management integrated circuit (PMIC), must not be able to drive a wire connected to a physical confirmation button.

Touch controller considerations

Protected Confirmation can use on-screen software buttons as input. Anytime the touch controller is being driven by the TEE, measures must be taken to sanitize the touch controller's state.

Note: The availability of this feature isn't guaranteed. That is, a compromised Android System or Android Kernel may block the dialog. In this case, a confirmation token must not be issued.

Expected behavior

Interruptions

If the system interrupts the confirmation session because of an incoming phone call or power event, the HAL must report ResponseCode::Aborted. Apps get the onCanceled() callback and know the user didn't choose an action. Alarms don't need to abort the session but do need to notify the user. Notification overlays of any kind aren't allowed while the dialog is active.

Input grace period

After Protected Confirmation is initiated, the input needs to remain inactive for a minimum of 1 second before it becomes responsive to user interaction. This grace period ensures that the user has a chance to react to an unexpected confirmation dialog. This grace period must be enforced by the trusted app.

Screen rotation

Portrait is the only mandated mode, and screen rotation isn't supported. Screen rotation allows the potential for abuse on a compromised system, such as misleading button placement or body text manipulation.

Body text rendering failures

There's a hard boundary of 6144 (0x1800) bytes for the body text including extra nondisplayed data and CBOR header information. In addition, there's a soft boundary that must be enforced. If the rendered message doesn't completely fit in the available screen space, ensure that Protected Confirmation aborts and the transaction is canceled. If MessageSize exceeds the maximum allowable size, your implementation must return UIErrorMessageTooLong on promptUserConfirmation.

Best practice is to format the body text after receiving the API call. The body text must be shown to the user in full.

Secondary displays

Secondary displays are supported under certain conditions. The integrity of output and user input must be maintained, and no misleading information can be displayed through other means. Otherwise, the dialog may only be displayed on the primary display and all other displays should be deactivated or blank. Streaming and screen-sharing solutions aren't allowed to display the dialog or generate confirmations.