443 lines
18 KiB
Java
443 lines
18 KiB
Java
/*
|
|
* Copyright (C) 2015 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.nfc.cardemulation;
|
|
|
|
import android.annotation.FlaggedApi;
|
|
import android.annotation.NonNull;
|
|
import android.annotation.SdkConstant;
|
|
import android.annotation.SdkConstant.SdkConstantType;
|
|
import android.app.Service;
|
|
import android.content.Intent;
|
|
import android.content.pm.PackageManager;
|
|
import android.nfc.NfcAdapter;
|
|
import android.os.Bundle;
|
|
import android.os.Handler;
|
|
import android.os.IBinder;
|
|
import android.os.Message;
|
|
import android.os.Messenger;
|
|
import android.os.RemoteException;
|
|
import android.util.Log;
|
|
|
|
import java.util.ArrayList;
|
|
import java.util.List;
|
|
|
|
/**
|
|
* <p>HostApduService is a convenience {@link Service} class that can be
|
|
* extended to emulate an NFC card inside an Android
|
|
* service component.
|
|
*
|
|
* <div class="special reference">
|
|
* <h3>Developer Guide</h3>
|
|
* For a general introduction to card emulation, see
|
|
* <a href="{@docRoot}guide/topics/connectivity/nfc/hce.html">
|
|
* Host-based Card Emulation</a>.</p>
|
|
* </div>
|
|
*
|
|
* <h3>NFC Protocols</h3>
|
|
* <p>Cards emulated by this class are based on the NFC-Forum ISO-DEP
|
|
* protocol (based on ISO/IEC 14443-4) and support processing
|
|
* command Application Protocol Data Units (APDUs) as
|
|
* defined in the ISO/IEC 7816-4 specification.
|
|
*
|
|
* <h3>Service selection</h3>
|
|
* <p>When a remote NFC device wants to talk to your
|
|
* service, it sends a so-called
|
|
* "SELECT AID" APDU as defined in the ISO/IEC 7816-4 specification.
|
|
* The AID is an application identifier defined in ISO/IEC 7816-4.
|
|
*
|
|
* <p>The registration procedure for AIDs is defined in the
|
|
* ISO/IEC 7816-5 specification. If you don't want to register an
|
|
* AID, you are free to use AIDs in the proprietary range:
|
|
* bits 8-5 of the first byte must each be set to '1'. For example,
|
|
* "0xF00102030405" is a proprietary AID. If you do use proprietary
|
|
* AIDs, it is recommended to choose an AID of at least 6 bytes,
|
|
* to reduce the risk of collisions with other applications that
|
|
* might be using proprietary AIDs as well.
|
|
*
|
|
* <h3>AID groups</h3>
|
|
* <p>In some cases, a service may need to register multiple AIDs
|
|
* to implement a certain application, and it needs to be sure
|
|
* that it is the default handler for all of these AIDs (as opposed
|
|
* to some AIDs in the group going to another service).
|
|
*
|
|
* <p>An AID group is a list of AIDs that should be considered as
|
|
* belonging together by the OS. For all AIDs in an AID group, the
|
|
* OS will guarantee one of the following:
|
|
* <ul>
|
|
* <li>All AIDs in the group are routed to this service
|
|
* <li>No AIDs in the group are routed to this service
|
|
* </ul>
|
|
* In other words, there is no in-between state, where some AIDs
|
|
* in the group can be routed to this service, and some to another.
|
|
* <h3>AID groups and categories</h3>
|
|
* <p>Each AID group can be associated with a category. This allows
|
|
* the Android OS to classify services, and it allows the user to
|
|
* set defaults at the category level instead of the AID level.
|
|
*
|
|
* <p>You can use
|
|
* {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)}
|
|
* to determine if your service is the default handler for a category.
|
|
*
|
|
* <p>In this version of the platform, the only known categories
|
|
* are {@link CardEmulation#CATEGORY_PAYMENT} and {@link CardEmulation#CATEGORY_OTHER}.
|
|
* AID groups without a category, or with a category that is not recognized
|
|
* by the current platform version, will automatically be
|
|
* grouped into the {@link CardEmulation#CATEGORY_OTHER} category.
|
|
* <h3>Service AID registration</h3>
|
|
* <p>To tell the platform which AIDs groups
|
|
* are requested by this service, a {@link #SERVICE_META_DATA}
|
|
* entry must be included in the declaration of the service. An
|
|
* example of a HostApduService manifest declaration is shown below:
|
|
* <pre> <service android:name=".MyHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE">
|
|
* <intent-filter>
|
|
* <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE"/>
|
|
* </intent-filter>
|
|
* <meta-data android:name="android.nfc.cardemulation.host_apdu_ervice" android:resource="@xml/apduservice"/>
|
|
* </service></pre>
|
|
*
|
|
* This meta-data tag points to an apduservice.xml file.
|
|
* An example of this file with a single AID group declaration is shown below:
|
|
* <pre>
|
|
* <host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
|
|
* android:description="@string/servicedesc" android:requireDeviceUnlock="false">
|
|
* <aid-group android:description="@string/aiddescription" android:category="other">
|
|
* <aid-filter android:name="F0010203040506"/>
|
|
* <aid-filter android:name="F0394148148100"/>
|
|
* </aid-group>
|
|
* </host-apdu-service>
|
|
* </pre>
|
|
*
|
|
* <p>The {@link android.R.styleable#HostApduService <host-apdu-service>} is required
|
|
* to contain a
|
|
* {@link android.R.styleable#HostApduService_description <android:description>}
|
|
* attribute that contains a user-friendly description of the service that may be shown in UI.
|
|
* The
|
|
* {@link android.R.styleable#HostApduService_requireDeviceUnlock <requireDeviceUnlock>}
|
|
* attribute can be used to specify that the device must be unlocked before this service
|
|
* can be invoked to handle APDUs.
|
|
* <p>The {@link android.R.styleable#HostApduService <host-apdu-service>} must
|
|
* contain one or more {@link android.R.styleable#AidGroup <aid-group>} tags.
|
|
* Each {@link android.R.styleable#AidGroup <aid-group>} must contain one or
|
|
* more {@link android.R.styleable#AidFilter <aid-filter>} tags, each of which
|
|
* contains a single AID. The AID must be specified in hexadecimal format, and contain
|
|
* an even number of characters.
|
|
* <h3>AID conflict resolution</h3>
|
|
* Multiple HostApduServices may be installed on a single device, and the same AID
|
|
* can be registered by more than one service. The Android platform resolves AID
|
|
* conflicts depending on which category an AID belongs to. Each category may
|
|
* have a different conflict resolution policy. For example, for some categories
|
|
* the user may be able to select a default service in the Android settings UI.
|
|
* For other categories, to policy may be to always ask the user which service
|
|
* is to be invoked in case of conflict.
|
|
*
|
|
* To query the conflict resolution policy for a certain category, see
|
|
* {@link CardEmulation#getSelectionModeForCategory(String)}.
|
|
*
|
|
* <h3>Data exchange</h3>
|
|
* <p>Once the platform has resolved a "SELECT AID" command APDU to a specific
|
|
* service component, the "SELECT AID" command APDU and all subsequent
|
|
* command APDUs will be sent to that service through
|
|
* {@link #processCommandApdu(byte[], Bundle)}, until either:
|
|
* <ul>
|
|
* <li>The NFC link is broken</li>
|
|
* <li>A "SELECT AID" APDU is received which resolves to another service</li>
|
|
* </ul>
|
|
* These two scenarios are indicated by a call to {@link #onDeactivated(int)}.
|
|
*
|
|
* <p class="note">Use of this class requires the
|
|
* {@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present
|
|
* on the device.
|
|
*
|
|
*/
|
|
public abstract class HostApduService extends Service {
|
|
/**
|
|
* The {@link Intent} action that must be declared as handled by the service.
|
|
*/
|
|
@SdkConstant(SdkConstantType.SERVICE_ACTION)
|
|
public static final String SERVICE_INTERFACE =
|
|
"android.nfc.cardemulation.action.HOST_APDU_SERVICE";
|
|
|
|
/**
|
|
* The name of the meta-data element that contains
|
|
* more information about this service.
|
|
*/
|
|
public static final String SERVICE_META_DATA =
|
|
"android.nfc.cardemulation.host_apdu_service";
|
|
|
|
/**
|
|
* Reason for {@link #onDeactivated(int)}.
|
|
* Indicates deactivation was due to the NFC link
|
|
* being lost.
|
|
*/
|
|
public static final int DEACTIVATION_LINK_LOSS = 0;
|
|
|
|
/**
|
|
* Reason for {@link #onDeactivated(int)}.
|
|
*
|
|
* <p>Indicates deactivation was due to a different AID
|
|
* being selected (which implicitly deselects the AID
|
|
* currently active on the logical channel).
|
|
*
|
|
* <p>Note that this next AID may still be resolved to this
|
|
* service, in which case {@link #processCommandApdu(byte[], Bundle)}
|
|
* will be called again.
|
|
*/
|
|
public static final int DEACTIVATION_DESELECTED = 1;
|
|
|
|
static final String TAG = "ApduService";
|
|
|
|
/**
|
|
* MSG_COMMAND_APDU is sent by NfcService when
|
|
* a 7816-4 command APDU has been received.
|
|
*
|
|
* @hide
|
|
*/
|
|
public static final int MSG_COMMAND_APDU = 0;
|
|
|
|
/**
|
|
* MSG_RESPONSE_APDU is sent to NfcService to send
|
|
* a response APDU back to the remote device.
|
|
*
|
|
* @hide
|
|
*/
|
|
public static final int MSG_RESPONSE_APDU = 1;
|
|
|
|
/**
|
|
* MSG_DEACTIVATED is sent by NfcService when
|
|
* the current session is finished; either because
|
|
* another AID was selected that resolved to
|
|
* another service, or because the NFC link
|
|
* was deactivated.
|
|
*
|
|
* @hide
|
|
*/
|
|
public static final int MSG_DEACTIVATED = 2;
|
|
|
|
/**
|
|
*
|
|
* @hide
|
|
*/
|
|
public static final int MSG_UNHANDLED = 3;
|
|
|
|
/**
|
|
* @hide
|
|
*/
|
|
public static final int MSG_POLLING_LOOP = 4;
|
|
|
|
/**
|
|
* @hide
|
|
*/
|
|
public static final String KEY_DATA = "data";
|
|
|
|
/**
|
|
* @hide
|
|
*/
|
|
public static final String KEY_POLLING_LOOP_FRAMES_BUNDLE =
|
|
"android.nfc.cardemulation.POLLING_FRAMES";
|
|
|
|
/**
|
|
* Messenger interface to NfcService for sending responses.
|
|
* Only accessed on main thread by the message handler.
|
|
*
|
|
* @hide
|
|
*/
|
|
Messenger mNfcService = null;
|
|
|
|
final Messenger mMessenger = new Messenger(new MsgHandler());
|
|
|
|
final class MsgHandler extends Handler {
|
|
@Override
|
|
public void handleMessage(Message msg) {
|
|
switch (msg.what) {
|
|
case MSG_COMMAND_APDU:
|
|
Bundle dataBundle = msg.getData();
|
|
if (dataBundle == null) {
|
|
return;
|
|
}
|
|
if (mNfcService == null) mNfcService = msg.replyTo;
|
|
|
|
byte[] apdu = dataBundle.getByteArray(KEY_DATA);
|
|
if (apdu != null) {
|
|
HostApduService has = HostApduService.this;
|
|
byte[] responseApdu = processCommandApdu(apdu, null);
|
|
if (responseApdu != null) {
|
|
if (mNfcService == null) {
|
|
Log.e(TAG, "Response not sent; service was deactivated.");
|
|
return;
|
|
}
|
|
Message responseMsg = Message.obtain(null, MSG_RESPONSE_APDU);
|
|
Bundle responseBundle = new Bundle();
|
|
responseBundle.putByteArray(KEY_DATA, responseApdu);
|
|
responseMsg.setData(responseBundle);
|
|
responseMsg.replyTo = mMessenger;
|
|
try {
|
|
mNfcService.send(responseMsg);
|
|
} catch (RemoteException e) {
|
|
Log.e("TAG", "Response not sent; RemoteException calling into " +
|
|
"NfcService.");
|
|
}
|
|
}
|
|
} else {
|
|
Log.e(TAG, "Received MSG_COMMAND_APDU without data.");
|
|
}
|
|
break;
|
|
case MSG_RESPONSE_APDU:
|
|
if (mNfcService == null) {
|
|
Log.e(TAG, "Response not sent; service was deactivated.");
|
|
return;
|
|
}
|
|
try {
|
|
msg.replyTo = mMessenger;
|
|
mNfcService.send(msg);
|
|
} catch (RemoteException e) {
|
|
Log.e(TAG, "RemoteException calling into NfcService.");
|
|
}
|
|
break;
|
|
case MSG_DEACTIVATED:
|
|
// Make sure we won't call into NfcService again
|
|
mNfcService = null;
|
|
onDeactivated(msg.arg1);
|
|
break;
|
|
case MSG_UNHANDLED:
|
|
if (mNfcService == null) {
|
|
Log.e(TAG, "notifyUnhandled not sent; service was deactivated.");
|
|
return;
|
|
}
|
|
try {
|
|
msg.replyTo = mMessenger;
|
|
mNfcService.send(msg);
|
|
} catch (RemoteException e) {
|
|
Log.e(TAG, "RemoteException calling into NfcService.");
|
|
}
|
|
break;
|
|
case MSG_POLLING_LOOP:
|
|
if (android.nfc.Flags.nfcReadPollingLoop()) {
|
|
ArrayList<PollingFrame> pollingFrames =
|
|
msg.getData().getParcelableArrayList(
|
|
KEY_POLLING_LOOP_FRAMES_BUNDLE, PollingFrame.class);
|
|
processPollingFrames(pollingFrames);
|
|
}
|
|
break;
|
|
default:
|
|
super.handleMessage(msg);
|
|
}
|
|
}
|
|
}
|
|
|
|
@Override
|
|
public final IBinder onBind(Intent intent) {
|
|
return mMessenger.getBinder();
|
|
}
|
|
|
|
/**
|
|
* Sends a response APDU back to the remote device.
|
|
*
|
|
* <p>Note: this method may be called from any thread and will not block.
|
|
* @param responseApdu A byte-array containing the reponse APDU.
|
|
*/
|
|
public final void sendResponseApdu(byte[] responseApdu) {
|
|
Message responseMsg = Message.obtain(null, MSG_RESPONSE_APDU);
|
|
Bundle dataBundle = new Bundle();
|
|
dataBundle.putByteArray(KEY_DATA, responseApdu);
|
|
responseMsg.setData(dataBundle);
|
|
try {
|
|
mMessenger.send(responseMsg);
|
|
} catch (RemoteException e) {
|
|
Log.e("TAG", "Local messenger has died.");
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Calling this method allows the service to tell the OS
|
|
* that it won't be able to complete this transaction -
|
|
* for example, because it requires data connectivity
|
|
* that is not present at that moment.
|
|
*
|
|
* The OS may use this indication to give the user a list
|
|
* of alternative applications that can handle the last
|
|
* AID that was selected. If the user would select an
|
|
* application from the list, that action by itself
|
|
* will not cause the default to be changed; the selected
|
|
* application will be invoked for the next tap only.
|
|
*
|
|
* If there are no other applications that can handle
|
|
* this transaction, the OS will show an error dialog
|
|
* indicating your service could not complete the
|
|
* transaction.
|
|
*
|
|
* <p>Note: this method may be called anywhere between
|
|
* the first {@link #processCommandApdu(byte[], Bundle)}
|
|
* call and a {@link #onDeactivated(int)} call.
|
|
*/
|
|
public final void notifyUnhandled() {
|
|
Message unhandledMsg = Message.obtain(null, MSG_UNHANDLED);
|
|
try {
|
|
mMessenger.send(unhandledMsg);
|
|
} catch (RemoteException e) {
|
|
Log.e("TAG", "Local messenger has died.");
|
|
}
|
|
}
|
|
|
|
/**
|
|
* This method is called when polling frames have been received from a
|
|
* remote device. If the device is in observe mode, the service should
|
|
* call {@link NfcAdapter#allowTransaction()} once it is ready to proceed
|
|
* with the transaction. If the device is not in observe mode, the service
|
|
* can use this polling frame information to determine how to proceed if it
|
|
* subsequently has {@link #processCommandApdu(byte[], Bundle)} called. The
|
|
* service must override this method inorder to receive polling frames,
|
|
* otherwise the base implementation drops the frame.
|
|
*
|
|
* @param frame A description of the polling frame.
|
|
*/
|
|
@FlaggedApi(android.nfc.Flags.FLAG_NFC_READ_POLLING_LOOP)
|
|
public void processPollingFrames(@NonNull List<PollingFrame> frame) {
|
|
}
|
|
|
|
/**
|
|
* <p>This method will be called when a command APDU has been received
|
|
* from a remote device. A response APDU can be provided directly
|
|
* by returning a byte-array in this method. Note that in general
|
|
* response APDUs must be sent as quickly as possible, given the fact
|
|
* that the user is likely holding their device over an NFC reader
|
|
* when this method is called.
|
|
*
|
|
* <p class="note">If there are multiple services that have registered for the same
|
|
* AIDs in their meta-data entry, you will only get called if the user has
|
|
* explicitly selected your service, either as a default or just for the next tap.
|
|
*
|
|
* <p class="note">This method is running on the main thread of your application.
|
|
* If you cannot return a response APDU immediately, return null
|
|
* and use the {@link #sendResponseApdu(byte[])} method later.
|
|
*
|
|
* @param commandApdu The APDU that was received from the remote device
|
|
* @param extras A bundle containing extra data. May be null.
|
|
* @return a byte-array containing the response APDU, or null if no
|
|
* response APDU can be sent at this point.
|
|
*/
|
|
public abstract byte[] processCommandApdu(byte[] commandApdu, Bundle extras);
|
|
|
|
/**
|
|
* This method will be called in two possible scenarios:
|
|
* <li>The NFC link has been deactivated or lost
|
|
* <li>A different AID has been selected and was resolved to a different
|
|
* service component
|
|
* @param reason Either {@link #DEACTIVATION_LINK_LOSS} or {@link #DEACTIVATION_DESELECTED}
|
|
*/
|
|
public abstract void onDeactivated(int reason);
|
|
}
|