confirmationui/aidl/android/hardware/confirmationui/IConfirmationUI.aidl

/*
 * Copyright (C) 2022 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;

import android.hardware.confirmationui.IConfirmationResultCallback;
import android.hardware.confirmationui.UIOption;
import android.hardware.security.keymint.HardwareAuthToken;

@VintfStability
interface IConfirmationUI {
    // Possible Errors.
    /**
     * API call succeeded or the user gave approval (result callback).
     */
    const int OK = 0;
    /**
     * The user canceled the TUI (result callback).
     */
    const int CANCELED = 1;
    /**
     * IConfirmationUI::abort() was called. (result callback).
     */
    const int ABORTED = 2;
    /**
     * Cannot start another prompt.
     */
    const int OPERATION_PENDING = 3;
    /**
     * IConfirmationUI::deliverSecureInputEvent call was ignored.
     */
    const int IGNORED = 4;
    /**
     * An unexpected system error occurred.
     */
    const int SYSTEM_ERROR = 5;
    /**
     * Returned by an unimplemented API call.
     */
    const int UNIMPLEMENTED = 6;
    /**
     * This is returned when an error is diagnosed that should have been
     * caught by earlier input sanitization. Should never be seen in production.
     */
    const int UNEXPECTED = 7;
    /**
     * General UI error.
     */
    const int UI_ERROR = 0x10000;
    /**
     * This is returned if there is no corresponding glyph for a character.
     */
    const int UI_ERROR_MISSING_GLYPH = 0x10001;
    /**
     * The implementation must return this error code on promptUserConfirmation if the
     * resulting formatted message does not fit into MAX_MESSAGE_SIZE bytes. It is
     * advised that the implementation formats the message upon receiving this API call to
     * be able to diagnose this syndrome.
     */
    const int UI_ERROR_MESSAGE_TOO_LONG = 0x10002;
    /**
     * This is returned if the UTF8 encoding is malformed.
     */
    const int UI_ERROR_MALFORMED_UTF8ENCODING = 0x10003;

    // Constants
    /**
     * The test key is 32byte word with all bytes set to TEST_KEY_BYTE.
     */
    const int TEST_KEY_BYTE = 0xA5;
    /**
     * This defines the maximum message size. This indirectly limits the size of the prompt text
     * and the extra data that can be passed to the confirmation UI. The prompt text and extra data
     * must fit in to this size including CBOR header information.
     */
    const int MAX_MESSAGE_SIZE = 0x1800;

    /**
     * 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
     * IConfirmationUI::ABORTED.
     */
    void abort();

    /**
     * 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.aidl for details.
     *
     * @param secureInputToken An authentication token as generated by Android authentication
     *                         providers.
     */
    void deliverSecureInputEvent(in HardwareAuthToken secureInputToken);

    /**
     * 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.
     *
     * Service status return:
     *
     * 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.
     * OPERATION_PENDING is returned when the confirmation provider is currently
     *                      in use.
     * SYSTEM_ERROR an error occurred trying to communicate with the confirmation
     *                      provider (e.g. trusted app).
     * UI_ERROR the confirmation provider encountered an issue with displaying
     *                      the prompt text to the user.
     *
     * @param resultCB Implementation of IResultCallback. Used by the implementation to report
     *                 the result of the current pending user prompt.
     *
     * @param promptText UTF-8 encoded bytes 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 UIOptions.aidl for possible options.
     */
    void promptUserConfirmation(in IConfirmationResultCallback resultCB, in byte[] promptText,
            in byte[] extraData, in @utf8InCpp String locale, in UIOption[] uiOptions);
}