1 /* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware.secure_element@1.0; 18 19 import ISecureElementHalCallback; 20 21 /** According to ISO/IEC 7816 */ 22 interface ISecureElement { 23 /** 24 * Initializes the Secure Element. This may include updating the applet 25 * and/or vendor-specific initialization. 26 * 27 * HAL service must send onStateChange() with connected equal to true 28 * after all the initialization has been successfully completed. 29 * Clients must wait for a onStateChange(true) before opening channels. 30 * 31 * @param clientCallback callback used to sent status of the SE back to the 32 * client 33 */ 34 init(ISecureElementHalCallback clientCallback); 35 36 /** 37 * Returns Answer to Reset as per ISO/IEC 7816 38 * 39 * @return response containing the response. Empty vector if Secure Element 40 * doesn't support ATR. 41 */ 42 getAtr() generates (vec<uint8_t> response); 43 44 /** 45 * Returns the current state of the card. 46 * 47 * This is particularly useful for removable 48 * Secure Elements like UICC, Secure Elements on SD cards etc. 49 * 50 * @return present true if present, false otherwise 51 */ 52 isCardPresent() generates (bool present); 53 54 /** 55 * Transmits an APDU command (as per ISO/IEC 7816) to the SE. 56 * 57 * @param data APDU command to be sent 58 * @return response to the command. In case of error in communicating with 59 * the secure element, an empty vector is returned. 60 */ 61 transmit(vec<uint8_t> data) generates (vec<uint8_t> response); 62 63 /** 64 * Opens a logical channel with the Secure Element, selecting the applet 65 * represented by the Application ID (AID). 66 * 67 * @param aid AID to uniquely identify the applet on the Secure Element 68 * @param p2 P2 paramter of SELECT APDU as per ISO 7816-4 69 * @return status SecureElementStatus::SUCCESS on success, 70 * SecureElementStatus::CHANNEL_NOT_AVAILABLE if secure 71 * element has reached the maximum limit on the number of 72 * channels it can support, 73 * SecureElementStatus::NO_SUCH_ELEMENT_ERROR if AID provided 74 * doesn't match any applet on the secure element and 75 * SecureElementStatus::UNSUPPORTED_OPERATION if operation 76 * provided by the P2 parameter is not permitted by the 77 * applet. 78 * SecureElementStatus::IOERROR if there was an error 79 * communicating with the Secure Element. 80 * @return response On success, response to SELECT command is returned 81 * empty vector on failure. 82 */ 83 openLogicalChannel(vec<uint8_t> aid, uint8_t p2) 84 generates (LogicalChannelResponse response, SecureElementStatus status); 85 86 87 /** 88 * Opens a basic channel with the Secure Element, selecting the applet 89 * represented by the Application ID (AID). 90 * 91 * @param aid AID to uniquely identify the applet on the Secure Element 92 * @param p2 P2 paramter of SELECT APDU as per ISO 7816-4 93 * @return status SecureElementStatus::SUCCESS on success, 94 * SecureElementStatus::CHANNEL_NOT_AVAILABLE if secure 95 * element has reached the maximum limit on the number of 96 * channels it can support, 97 * SecureElementStatus::NO_SUCH_ELEMENT_ERROR if AID provided 98 * doesn't match any applet on the secure element and 99 * SecureElementStatus::UNSUPPORTED_OPERATION if operation 100 * provided by the P2 parameter is not permitted by the 101 * applet. 102 * SecureElementStatus::IOERROR if there was an error 103 * communicating with the Secure Element. 104 * @return selectResponse On success, response to SELECT command is returned 105 * empty vector on failure. 106 */ 107 openBasicChannel(vec<uint8_t> aid, uint8_t p2) 108 generates (vec<uint8_t> selectResponse, SecureElementStatus status); 109 110 /** 111 * Closes the channel indicated by the channelNumber. 112 * 113 * Closing a basic channel, i.e with channelNumber 0 must return 114 * SecureElementStatus::FAILED. 115 * 116 * @param channelNumber to be closed 117 * @return status SecureElementStatus::SUCCESS on success and 118 * SecureElementStatus::FAILED on error. 119 */ 120 closeChannel(uint8_t channelNumber) generates (SecureElementStatus status); 121 }; 122
