Evolution-x/hardware_interfaces
1
0
Fork 0
mirror of https://github.com/Evolution-X/hardware_interfaces synced 2026-02-01 10:44:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

ConfirmationUI HAL definition

Browse Source 
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
This commit is contained in:
Janis Danisevskis
2017-10-24 10:22:43 -07:00
parent e6a8a00fc2
commit b70f2b2521
4 changed files with 273 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
confirmationui/1.0/Android.bp Normal file
View File

@@ -0,0 +1,27 @@
// This file is autogenerated by hidl-gen -Landroidbp.
hidl_interface {
name: "android.hardware.confirmationui@1.0",
root: "android.hardware",
vndk: {
enabled: true,
},
srcs: [
"types.hal",
"IConfirmationResultCallback.hal",
"IConfirmationUI.hal",
],
interfaces: [
"android.hardware.keymaster@4.0",
"android.hidl.base@1.0",
],
types: [
"MessageSize",
"ResponseCode",
"TestKeyBits",
"TestModeCommands",
"UIOption",
],
gen_java: false,
}

61
confirmationui/1.0/IConfirmationResultCallback.hal Normal file
View File

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

81
confirmationui/1.0/IConfirmationUI.hal Normal file
View File

@@ -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();
};

104
confirmationui/1.0/types.hal Normal file
View File

@@ -0,0 +1,104 @@
/*
* 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,
};