ConfirmationUI HAL definition (b70f2b25) · Commits · e / os / android_hardware_interfaces

confirmationui/1.0/Android.bp

0 → 100644

+27 −0

Original line number	Original line	Diff line number	Diff line
			// 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,
			}

confirmationui/1.0/IConfirmationResultCallback.hal

0 → 100644

+61 −0

Original line number	Original line	Diff line number	Diff line
			/*
			* 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);
			};

confirmationui/1.0/IConfirmationUI.hal

0 → 100644

+81 −0

Original line number	Original line	Diff line number	Diff line
			/*
			* 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();
			};

confirmationui/1.0/types.hal

0 → 100644

+104 −0

Original line number	Original line	Diff line number	Diff line
			/*
			* 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,
			};