1/*
2 * Copyright (C) 2017 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.confirmationui@1.0;
18
19import android.hardware.keymaster@4.0::HardwareAuthToken;
20import IConfirmationResultCallback;
21
22interface IConfirmationUI {
23    /**
24     * Asynchronously initiates a confirmation UI dialog prompting the user to confirm a given text.
25     * The TUI prompt must be implemented in such a way that a positive response indicates with
26     * high confidence that a user has seen the given prompt text even if the Android framework
27     * including the kernel was compromised.
28     *
29     * @param resultCB Implementation of IResultCallback. Used by the implementation to report
30     *                 the result of the current pending user prompt.
31     *
32     * @param promptText UTF-8 encoded string which is to be presented to the user.
33     *
34     * @param extraData A binary blob that must be included in the formatted output message as is.
35     *                  It is opaque to the implementation. Implementations must neither interpret
36     *                  nor modify the content.
37     *
38     * @param locale String specifying the locale that must be used by the TUI dialog. The string
39     *                      is an IETF BCP 47 tag.
40     *
41     * @param uiOptions A set of uiOptions manipulating how the confirmation prompt is displayed.
42     *                  Refer to UIOption in types.hal for possible options.
43     *
44     * @return error  - OK: IFF the dialog was successfully started. In this case, and only in this
45     *                      case, the implementation must, eventually, call the callback to
46     *                      indicate completion.
47     *                - OperationPending: Is returned when the confirmation provider is currently
48     *                      in use.
49     *                - SystemError: An error occurred trying to communicate with the confirmation
50     *                      provider (e.g. trusted app).
51     *                - UIError: The confirmation provider encountered an issue with displaying
52     *                      the prompt text to the user.
53     */
54    promptUserConfirmation(IConfirmationResultCallback resultCB, string promptText,
55                           vec<uint8_t> extraData, string locale, vec<UIOption> uiOptions)
56        generates(ResponseCode error);
57
58    /**
59     * DeliverSecureInput is used by the framework to deliver a secure input event to the
60     * confirmation provider.
61     *
62     * VTS test mode:
63     * This function can be used to test certain code paths non-interactively. See TestModeCommands
64     * in types.hal for details.
65     *
66     * @param secureInputToken An authentication token as generated by Android authentication
67     *                         providers.
68     *
69     * @return error - Ignored: Unless used for testing (See TestModeCommands).
70     */
71    deliverSecureInputEvent(HardwareAuthToken secureInputToken)
72        generates(ResponseCode error);
73
74    /**
75     * Aborts a pending user prompt. This allows the framework to gracefully end a TUI dialog.
76     * If a TUI operation was pending the corresponding call back is informed with
77     * ErrorCode::Aborted.
78     */
79    abort();
80};
81
82