confirmationui/1.0/types.hal

/*
 * 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;

/**
 * UI modification options.
 */
enum UIOption : uint32_t {
    /** Accessibility: Requests color inverted style. */
    AccessibilityInverted = 0,
    /** Accessibility: Requests magnified style. */
    AccessibilityMagnified = 1,
};

/**
 * Codes returned by ConfirmationUI API calls.
 */
enum ResponseCode : uint32_t {
    /** API call succeeded or the user gave approval (result callback). */
    OK = 0,
    /** The user canceled the TUI (result callback). */
    Canceled = 1,
    /** IConfirmationUI::abort() was called. (result callback). */
    Aborted = 2,
    /** Cannot start another prompt. */
    OperationPending = 3,
    /** IConfirmationUI::deliverSecureInputEvent call was ingored. */
    Ignored = 4,
    /** An unexpected system error occured. */
    SystemError = 5,
    /** Returned by an unimplemented API call. */
    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.
       */
    Unexpected = 7,
    /** General UI error. */
    UIError = 0x10000,
    UIErrorMissingGlyph,
    /**
     * The implementation must return this error code on promptUserConfirmation if the
     * resulting formatted message does not fit into MessageSize::MAX bytes. It is
     * advised that the implementation formats the message upon receiving this API call to
     * be able to diagnose this syndrome.
     */
    UIErrorMessageTooLong,
    UIErrorMalformedUTF8Encoding,
};

/**
 * 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.
 */
enum MessageSize : uint32_t { MAX = 0x1800 };

/**
 * The test key is 32byte word with all bytes set to TestKeyBits::BYTE.
 */
enum TestKeyBits: uint8_t { BYTE = 0xA5 };

/**
 * Test mode commands.
 *
 * IConfirmationUI::deliverSecureInputEvent can be used to test certain code paths.
 * To that end, the caller passes an auth token that has an HMAC keyed with the test key
 * (see TestKeyBits in types.hal). Implementations first check the HMAC against test key.
 * If the test key produces a matching HMAC, the implementation evaluates the challenge field
 * of the auth token against the values defined in TestModeCommand.
 * If the command indicates that a confirmation token is to be generated the test key MUST be used
 * to generate this confirmation token.
 *
 * See command code for individual test command descriptions.
 */
enum TestModeCommands: uint64_t {
    /**
     * Simulates the user pressing the OK button on the UI. If no operation is pending
     * ResponseCode::Ignored must be returned. A pending operation is finalized successfully
     * see IConfirmationResultCallback::result, however, the test key (see TestKeyBits) MUST be
     * used to generate the confirmation token.
     */
    OK_EVENT = 0,
    /**
     * Simulates the user pressing the CANCEL button on the UI. If no operation is pending
     * Result::Ignored must be returned. A pending operation is finalized as specified in
     * IConfirmationResultCallback.hal.
     */
    CANCEL_EVENT = 1,
};