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
19/**
20 * Callback interface passed to IConfirmationUI::promptUserConfirmation().
21 * Informs the caller about the result of the prompt operation.
22 */
23interface IConfirmationResultCallback {
24    /**
25     * This callback is called by the confirmation provider when it stops prompting the user.
26     * Iff the user has confirmed the prompted text, error is ErrorCode::OK and the
27     * parameters formattedMessage and confirmationToken hold the values needed to request
28     * a signature from keymaster.
29     * In all other cases formattedMessage and confirmationToken must be of length 0.
30     *
31     * @param error - OK: IFF the user has confirmed the prompt.
32     *              - Canceled: If the user has pressed the cancel button.
33     *              - Aborted: If IConfirmationUI::abort() was called.
34     *              - SystemError: If an unexpected System error occurred that prevented the TUI
35     *                             from being shut down gracefully.
36     * @param formattedMessage holds the prompt text and extra data.
37     *                         The message is CBOR (RFC 7049) encoded and has the following format:
38     *                         CBOR_MAP{ "prompt", <promptText>, "extra", <extraData> }
39     *                         The message is a CBOR encoded map (type 5) with the keys
40     *                         "prompt" and "extra". The keys are encoded as CBOR text string
41     *                         (type 3). The value <promptText> is encoded as CBOR text string
42     *                         (type 3), and the value <extraData> is encoded as CBOR byte string
43     *                         (type 2). The map must have exactly one key value pair for each of
44     *                         the keys "prompt" and "extra". Other keys are not allowed.
45     *                         The value of "prompt" is given by the proptText argument to
46     *                         IConfirmationUI::promptUserConfirmation and must not be modified
47     *                         by the implementation.
48     *                         The value of "extra" is given by the extraData argument to
49     *                         IConfirmationUI::promptUserConfirmation and must not be modified
50     *                         or interpreted by the implementation.
51     *
52     * @param confirmationToken a 32-byte HMAC-SHA256 value, computed over
53     *                          "confirmation token" || <formattedMessage>
54     *                          i.e. the literal UTF-8 encoded string "confirmation token", without
55     *                          the "", concatenated with the formatted message as returned in the
56     *                          formattedMessage argument. The HMAC is keyed with a 256-bit secret
57     *                          which is shared with Keymaster. In test mode the test key MUST be
58     *                          used (see types.hal TestModeCommands and TestKeyBits).
59     */
60    result(ResponseCode error, vec<uint8_t> formattedMessage, vec<uint8_t> confirmationToken);
61};
62