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

confirmationui/1.0/Android.bp

0 → 100644

+27 −0

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