omapi/java/android/se/omapi/Session.java

/*
 * 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.
 */
/*
 * Copyright (c) 2017, The Linux Foundation.
 */
/*
 * Contributed by: Giesecke & Devrient GmbH.
 */

package android.se.omapi;

import android.annotation.NonNull;
import android.annotation.Nullable;
import android.os.RemoteException;
import android.os.ServiceSpecificException;
import android.util.Log;

import java.io.IOException;
import java.util.NoSuchElementException;

/**
 * Instances of this class represent a connection session to one of the Secure
 * Elements available on the device. These objects can be used to get a
 * communication channel with an Applet in the Secure Element.
 * This channel can be the basic channel or a logical channel.
 *
 * @see <a href="http://simalliance.org">SIMalliance Open Mobile API  v3.0</a>
 */
public final class Session {

    private final Object mLock = new Object();
    private final SEService mService;
    private final Reader mReader;
    private final ISecureElementSession mSession;
    private static final String TAG = "OMAPI.Session";

    Session(@NonNull SEService service, @NonNull ISecureElementSession session,
            @NonNull Reader reader) {
        if (service == null || reader == null || session == null) {
            throw new IllegalArgumentException("Parameters cannot be null");
        }
        mService = service;
        mReader = reader;
        mSession = session;
    }

    /**
     * Get the reader that provides this session.
     *
     * @return The Reader object.
     */
    public @NonNull Reader getReader() {
        return mReader;
    }

    /**
     * Get the Answer to Reset of this Secure Element. <br>
     * The returned byte array can be null if the ATR for this Secure Element is
     * not available.
     *
     * @throws IllegalStateException if there was an error connecting to SE or
     *                               if the service was not connected.
     * @return the ATR as a byte array or null.
     */
    public @Nullable byte[] getATR() {
        if (!mService.isConnected()) {
            throw new IllegalStateException("service not connected to system");
        }
        try {
            return mSession.getAtr();
        } catch (RemoteException e) {
            throw new IllegalStateException(e.getMessage());
        }
    }

    /**
     * Close the connection with the Secure Element. This will close any
     * channels opened by this application with this Secure Element.
     */
    public void close() {
        if (!mService.isConnected()) {
            Log.e(TAG, "service not connected to system");
            return;
        }
        synchronized (mLock) {
            try {
                mSession.close();
            } catch (RemoteException e) {
                Log.e(TAG, "Error closing session", e);
            }
        }
    }

    /**
     * Tells if this session is closed.
     *
     * @return <code>true</code> if the session is closed, false otherwise.
     */
    public boolean isClosed() {
        try {
            return mSession.isClosed();
        } catch (RemoteException e) {
            // If there was an error here, then the session is considered close
            return true;
        }
    }

    /**
     * Close any channel opened on this session.
     */
    public void closeChannels() {
        if (!mService.isConnected()) {
            Log.e(TAG, "service not connected to system");
            return;
        }

        synchronized (mLock) {
            try {
                mSession.closeChannels();
            } catch (RemoteException e) {
                Log.e(TAG, "Error closing channels", e);
            }
        }
    }

    /**
     * Get an access to the basic channel, as defined in the ISO/IEC 7816-4 specification (the
     * one that has number 0). The obtained object is an instance of the Channel class.
     * If the AID is null, it means no Applet is to be selected on this channel and the default
     * Applet is used. If the AID is defined then the corresponding Applet is selected.
     * Once this channel has been opened by a device application, it is considered as "locked"
     * by this device application, and other calls to this method will return null, until the
     * channel is closed. Some Secure Elements (like the UICC) might always keep the basic channel
     * locked (i.e. return null to applications), to prevent access to the basic channel, while
     * some other might return a channel object implementing some kind of filtering on the
     * commands, restricting the set of accepted command to a smaller set.
     * It is recommended for the UICC to reject the opening of the basic channel to a specific
     * applet, by always answering null to such a request.
     * For other Secure Elements, the recommendation is to accept opening the basic channel
     * on the default applet until another applet is selected on the basic channel. As there is no
     * other way than a reset to select again the default applet, the implementation of the
     * transport API should guarantee that the openBasicChannel(null) command will return
     * null until a reset occurs.
     * With previous release (V2.05) it was not possible to set P2 value, this value was always
     * set to '00'.Except for specific needs it is recommended to keep P2 to '00'. It is
     * recommended that the device allows all values for P2, however only the following values
     * are mandatory: '00', '04', '08', '0C'(as defined in [2])
     * The implementation of the underlying SELECT command within this method shall be
     * based on ISO 7816-4 with following options:
     * <ul>
     * <li>CLA = '00'</li>
     * <li>INS = 'A4'</li>
     * <li>P1 = '04' (Select by DF name/application identifier)</li>
     * </ul>
     *
     * The select response data can be retrieved with byte[] getSelectResponse().
     * The API shall handle received status word as follow. If the status word indicates that the
     * Secure Element was able to open a channel (e.g. status word '90 00' or status words
     * referencing a warning in ISO-7816-4: '62 XX' or '63 XX') the API shall keep the
     * channel opened and the next getSelectResponse() shall return the received status
     * word.
     * Other received status codes indicating that the Secure Element was able not to open a
     * channel shall be considered as an error and the corresponding channel shall not be
     * opened.
     * The function without P2 as parameter is provided for backwards compatibility and will
     * fall back to a select command with P2='00'.
     *
     * @param aid the AID of the Applet to be selected on this channel, as a
     *            byte array, or null if no Applet is to be selected.
     * @param p2 the P2 parameter of the SELECT APDU executed on this channel.
     * @throws IOException if there is a communication problem to the reader or
     *             the Secure Element.
     * @throws IllegalStateException if the Secure Element session is used after
     *             being closed.
     * @throws IllegalArgumentException if the aid's length is not within 5 to
     *             16 (inclusive).
     * @throws SecurityException if the calling application cannot be granted
     *             access to this AID or the default Applet on this
     *             session.
     * @throws NoSuchElementException if the AID on the Secure Element is not available or cannot be
     *             selected.
     * @throws UnsupportedOperationException if the given P2 parameter is not
     *             supported by the device
     * @return an instance of Channel if available or null.
     */
    public @Nullable Channel openBasicChannel(@Nullable byte[] aid, @Nullable byte p2)
            throws IOException {
        if (!mService.isConnected()) {
            throw new IllegalStateException("service not connected to system");
        }

        synchronized (mLock) {
            try {
                ISecureElementChannel channel = mSession.openBasicChannel(aid, p2,
                        mReader.getSEService().getListener());
                if (channel == null) {
                    return null;
                }
                return new Channel(mService, this, channel);
            } catch (ServiceSpecificException e) {
                if (e.errorCode == SEService.IO_ERROR) {
                    throw new IOException(e.getMessage());
                } else if (e.errorCode == SEService.NO_SUCH_ELEMENT_ERROR) {
                    throw new NoSuchElementException(e.getMessage());
                } else {
                    throw new IllegalStateException(e.getMessage());
                }
            } catch (RemoteException e) {
                throw new IllegalStateException(e.getMessage());
            }
        }
    }

    /**
     * This method is provided to ease the development of mobile application and for compliancy
     * with existing applications.
     * This method is equivalent to openBasicChannel(aid, P2=0x00)
     *
     * @param aid the AID of the Applet to be selected on this channel, as a
     *            byte array, or null if no Applet is to be selected.
     * @throws IOException if there is a communication problem to the reader or
     *             the Secure Element.
     * @throws IllegalStateException if the Secure Element session is used after
     *             being closed.
     * @throws IllegalArgumentException if the aid's length is not within 5 to
     *             16 (inclusive).
     * @throws SecurityException if the calling application cannot be granted
     *             access to this AID or the default Applet on this
     *             session.
     * @throws NoSuchElementException if the AID on the Secure Element is not available or cannot be
     *             selected.
     * @throws UnsupportedOperationException if the given P2 parameter is not
     *             supported by the device
     * @return an instance of Channel if available or null.
     */
    public @Nullable Channel openBasicChannel(@Nullable byte[] aid) throws IOException {
        return openBasicChannel(aid, (byte) 0x00);
    }

    /**
     * Open a logical channel with the Secure Element, selecting the Applet represented by
     * the given AID. If the AID is null, which means no Applet is to be selected on this
     * channel, the default Applet is used. It's up to the Secure Element to choose which
     * logical channel will be used.
     * With previous release (V2.05) it was not possible to set P2 value, this value was always
     * set to '00'.Except for specific needs it is recommended to keep P2 to '00'. It is
     * recommended that the device allows all values for P2, however only the following values
     * are mandatory: '00', '04', '08', '0C'(as defined in [2])
     * The implementation of the underlying SELECT command within this method shall be
     * based on ISO 7816-4 with following options:
     *
     * <ul>
     * <li>CLA = '01' to '03', '40 to 4F'</li>
     * <li>INS = 'A4'</li>
     * <li>P1 = '04' (Select by DF name/application identifier)</li>
     * </ul>
     *
     * The select response data can be retrieved with byte[] getSelectResponse().
     * The API shall handle received status word as follow. If the status word indicates that the
     * Secure Element was able to open a channel (e.g. status word '90 00' or status words
     * referencing a warning in ISO-7816-4: '62 XX' or '63 XX') the API shall keep the
     * channel opened and the next getSelectResponse() shall return the received status
     * word.
     * Other received status codes indicating that the Secure Element was able not to open a
     * channel shall be considered as an error and the corresponding channel shall not be
     * opened.
     * In case of UICC it is recommended for the API to reject the opening of the logical
     * channel without a specific AID, by always answering null to such a request.
     * The function without P2 as parameter is provided for backwards compatibility and will
     * fall back to a select command with P2=00.
     *
     * @param aid the AID of the Applet to be selected on this channel, as a
     *            byte array.
     * @param p2 the P2 parameter of the SELECT APDU executed on this channel.
     * @throws IOException if there is a communication problem to the reader or
     *             the Secure Element.
     * @throws IllegalStateException if the Secure Element is used after being
     *             closed.
     * @throws IllegalArgumentException if the aid's length is not within 5 to
     *             16 (inclusive).
     * @throws SecurityException if the calling application cannot be granted
     *             access to this AID or the default Applet on this
     *             session.
     * @throws NoSuchElementException if the AID on the Secure Element is not
     *             available or cannot be selected or a logical channel is already
     *             open to a non-multiselectable Applet.
     * @throws UnsupportedOperationException if the given P2 parameter is not
     *             supported by the device.
     * @return an instance of Channel. Null if the Secure Element is unable to
     *         provide a new logical channel.
     */
    public @Nullable Channel openLogicalChannel(@Nullable byte[] aid, @Nullable byte p2)
            throws IOException {
        if (!mService.isConnected()) {
            throw new IllegalStateException("service not connected to system");
        }
        synchronized (mLock) {
            try {
                ISecureElementChannel channel = mSession.openLogicalChannel(
                        aid,
                        p2,
                        mReader.getSEService().getListener());
                if (channel == null) {
                    return null;
                }
                return new Channel(mService, this, channel);
            } catch (ServiceSpecificException e) {
                if (e.errorCode == SEService.IO_ERROR) {
                    throw new IOException(e.getMessage());
                } else if (e.errorCode == SEService.NO_SUCH_ELEMENT_ERROR) {
                    throw new NoSuchElementException(e.getMessage());
                } else {
                    throw new IllegalStateException(e.getMessage());
                }
            } catch (RemoteException e) {
                throw new IllegalStateException(e.getMessage());
            }
        }
    }

    /**
     * This method is provided to ease the development of mobile application and for compliancy
     * with existing applications.
     * This method is equivalent to openLogicalChannel(aid, P2=0x00)
     *
     * @param aid the AID of the Applet to be selected on this channel, as a
     *            byte array.
     * @throws IOException if there is a communication problem to the reader or
     *             the Secure Element.
     * @throws IllegalStateException if the Secure Element is used after being
     *             closed.
     * @throws IllegalArgumentException if the aid's length is not within 5 to
     *             16 (inclusive).
     * @throws SecurityException if the calling application cannot be granted
     *             access to this AID or the default Applet on this
     *             session.
     * @throws NoSuchElementException if the AID on the Secure Element is not
     *             available or cannot be selected or a logical channel is already
     *             open to a non-multiselectable Applet.
     * @throws UnsupportedOperationException if the given P2 parameter is not
     *             supported by the device.
     * @return an instance of Channel. Null if the Secure Element is unable to
     *         provide a new logical channel.
     */
    public @Nullable Channel openLogicalChannel(@Nullable byte[] aid) throws IOException {
        return openLogicalChannel(aid, (byte) 0x00);
    }
}