• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
17package android.hardware.secure_element@1.0;
18
19import ISecureElementHalCallback;
20
21/** According to ISO/IEC 7816 */
22interface 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