xref: /aosp_15_r20/hardware/interfaces/secure_element/1.0/ISecureElement.hal (revision 4d7e907c777eeecc4c5bd7cf640a754fac206ff7)

/*
 * 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 [email protected];

import ISecureElementHalCallback;

/** According to ISO/IEC 7816 */
interface ISecureElement {
    /**
     * Initializes the Secure Element. This may include updating the applet
     * and/or vendor-specific initialization.
     *
     * HAL service must send onStateChange() with connected equal to true
     * after all the initialization has been successfully completed.
     * Clients must wait for a onStateChange(true) before opening channels.
     *
     * @param clientCallback callback used to sent status of the SE back to the
     *                       client
     */
    init(ISecureElementHalCallback clientCallback);

    /**
     * Returns Answer to Reset as per ISO/IEC 7816
     *
     * @return response containing the response. Empty vector if Secure Element
     *                  doesn't support ATR.
     */
    getAtr() generates (vec<uint8_t> response);

    /**
     * Returns the current state of the card.
     *
     * This is particularly useful for removable
     * Secure Elements like UICC, Secure Elements on SD cards etc.
     *
     * @return present true if present, false otherwise
     */
    isCardPresent() generates (bool present);

    /**
     * Transmits an APDU command (as per ISO/IEC 7816) to the SE.
     *
     * @param data APDU command to be sent
     * @return response to the command. In case of error in communicating with
     *                  the secure element, an empty vector is returned.
     */
     transmit(vec<uint8_t> data) generates (vec<uint8_t> response);

    /**
     * Opens a logical channel with the Secure Element, selecting the applet
     * represented by the Application ID (AID).
     *
     * @param aid AID to uniquely identify the applet on the Secure Element
     * @param p2 P2 paramter of SELECT APDU as per ISO 7816-4
     * @return status SecureElementStatus::SUCCESS on success,
     *                SecureElementStatus::CHANNEL_NOT_AVAILABLE if secure
     *                element has reached the maximum limit on the number of
     *                channels it can support,
     *                SecureElementStatus::NO_SUCH_ELEMENT_ERROR if AID provided
     *                doesn't match any applet on the secure element and
     *                SecureElementStatus::UNSUPPORTED_OPERATION if operation
     *                provided by the P2 parameter is not permitted by the
     *                applet.
     *                SecureElementStatus::IOERROR if there was an error
     *                communicating with the Secure Element.
     * @return response On success, response to SELECT command is returned
     *                        empty vector on failure.
     */
    openLogicalChannel(vec<uint8_t> aid, uint8_t p2)
        generates (LogicalChannelResponse response, SecureElementStatus status);


    /**
     * Opens a basic channel with the Secure Element, selecting the applet
     * represented by the Application ID (AID).
     *
     * @param aid AID to uniquely identify the applet on the Secure Element
     * @param p2 P2 paramter of SELECT APDU as per ISO 7816-4
     * @return status SecureElementStatus::SUCCESS on success,
     *                SecureElementStatus::CHANNEL_NOT_AVAILABLE if secure
     *                element has reached the maximum limit on the number of
     *                channels it can support,
     *                SecureElementStatus::NO_SUCH_ELEMENT_ERROR if AID provided
     *                doesn't match any applet on the secure element and
     *                SecureElementStatus::UNSUPPORTED_OPERATION if operation
     *                provided by the P2 parameter is not permitted by the
     *                applet.
     *                SecureElementStatus::IOERROR if there was an error
     *                communicating with the Secure Element.
     * @return selectResponse On success, response to SELECT command is returned
     *                        empty vector on failure.
     */
    openBasicChannel(vec<uint8_t> aid, uint8_t p2)
        generates (vec<uint8_t> selectResponse, SecureElementStatus status);

    /**
     * Closes the channel indicated by the channelNumber.
     *
     * Closing a basic channel, i.e with channelNumber 0 must return
     * SecureElementStatus::FAILED.
     *
     * @param channelNumber to be closed
     * @return status SecureElementStatus::SUCCESS on success and
     *                SecureElementStatus::FAILED on error.
     */
    closeChannel(uint8_t channelNumber) generates (SecureElementStatus status);
};