ConfirmationUI HAL definition
HAL definition for high assurance confirmation providers.
High assurance confirmation providers allow relying parties
to prompt the user for confirming a short piece of information.
If the user confirms, the result is a signed message indicating
that the user has seen the message. For a high assurance confirmation
provider this must also be true if Android and the Linux kernel
are compromised.
Bug: 63928580
Test: VTS tests in the following commit
Change-Id: I72017b39c01b4333d0146c648637a19fafcb7278
diff --git a/confirmationui/1.0/IConfirmationUI.hal b/confirmationui/1.0/IConfirmationUI.hal
new file mode 100644
index 0000000..db8055d
--- /dev/null
+++ b/confirmationui/1.0/IConfirmationUI.hal
@@ -0,0 +1,81 @@
+/*
+ * Copyright (C) 2017 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.confirmationui@1.0;
+
+import android.hardware.keymaster@4.0::HardwareAuthToken;
+import IConfirmationResultCallback;
+
+interface IConfirmationUI {
+ /**
+ * Asynchronously initiates a confirmation UI dialog prompting the user to confirm a given text.
+ * The TUI prompt must be implemented in such a way that a positive response indicates with
+ * high confidence that a user has seen the given prompt text even if the Android framework
+ * including the kernel was compromised.
+ *
+ * @param resultCB Implementation of IResultCallback. Used by the implementation to report
+ * the result of the current pending user prompt.
+ *
+ * @param promptText UTF-8 encoded string which is to be presented to the user.
+ *
+ * @param extraData A binary blob that must be included in the formatted output message as is.
+ * It is opaque to the implementation. Implementations must neither interpret
+ * nor modify the content.
+ *
+ * @param locale String specifying the locale that must be used by the TUI dialog. The string
+ * is an IETF BCP 47 tag.
+ *
+ * @param uiOptions A set of uiOptions manipulating how the confirmation prompt is displayed.
+ * Refer to UIOption in types.hal for possible options.
+ *
+ * @return error - OK: IFF the dialog was successfully started. In this case, and only in this
+ * case, the implementation must, eventually, call the callback to
+ * indicate completion.
+ * - OperationPending: Is returned when the confirmation provider is currently
+ * in use.
+ * - SystemError: An error occurred trying to communicate with the confirmation
+ * provider (e.g. trusted app).
+ * - UIError: The confirmation provider encountered an issue with displaying
+ * the prompt text to the user.
+ */
+ promptUserConfirmation(IConfirmationResultCallback resultCB, string promptText,
+ vec<uint8_t> extraData, string locale, vec<UIOption> uiOptions)
+ generates(ResponseCode error);
+
+ /**
+ * DeliverSecureInput is used by the framework to deliver a secure input event to the
+ * confirmation provider.
+ *
+ * VTS test mode:
+ * This function can be used to test certain code paths non-interactively. See TestModeCommands
+ * in types.hal for details.
+ *
+ * @param secureInputToken An authentication token as generated by Android authentication
+ * providers.
+ *
+ * @return error - Ignored: Unless used for testing (See TestModeCommands).
+ */
+ deliverSecureInputEvent(HardwareAuthToken secureInputToken)
+ generates(ResponseCode error);
+
+ /**
+ * Aborts a pending user prompt. This allows the framework to gracefully end a TUI dialog.
+ * If a TUI operation was pending the corresponding call back is informed with
+ * ErrorCode::Aborted.
+ */
+ abort();
+};
+