From b70f2b2521f518fe85ffd03948ac52948187d306 Mon Sep 17 00:00:00 2001 From: Janis Danisevskis Date: Tue, 24 Oct 2017 10:22:43 -0700 Subject: [PATCH] ConfirmationUI HAL definition 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 --- confirmationui/1.0/Android.bp | 27 +++++ .../1.0/IConfirmationResultCallback.hal | 61 ++++++++++ confirmationui/1.0/IConfirmationUI.hal | 81 ++++++++++++++ confirmationui/1.0/types.hal | 104 ++++++++++++++++++ 4 files changed, 273 insertions(+) create mode 100644 confirmationui/1.0/Android.bp create mode 100644 confirmationui/1.0/IConfirmationResultCallback.hal create mode 100644 confirmationui/1.0/IConfirmationUI.hal create mode 100644 confirmationui/1.0/types.hal diff --git a/confirmationui/1.0/Android.bp b/confirmationui/1.0/Android.bp new file mode 100644 index 0000000000..21acecba7e --- /dev/null +++ b/confirmationui/1.0/Android.bp @@ -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, +} + diff --git a/confirmationui/1.0/IConfirmationResultCallback.hal b/confirmationui/1.0/IConfirmationResultCallback.hal new file mode 100644 index 0000000000..03a10cfe6c --- /dev/null +++ b/confirmationui/1.0/IConfirmationResultCallback.hal @@ -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", , "extra", } + * 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 is encoded as CBOR text string + * (type 3), and the value 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" || + * 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 formattedMessage, vec confirmationToken); +}; diff --git a/confirmationui/1.0/IConfirmationUI.hal b/confirmationui/1.0/IConfirmationUI.hal new file mode 100644 index 0000000000..db8055d16c --- /dev/null +++ b/confirmationui/1.0/IConfirmationUI.hal @@ -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 extraData, string locale, vec 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(); +}; + diff --git a/confirmationui/1.0/types.hal b/confirmationui/1.0/types.hal new file mode 100644 index 0000000000..fd7ae6afdd --- /dev/null +++ b/confirmationui/1.0/types.hal @@ -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, +};